@explorins/pers-sdk 1.2.6 → 1.3.2

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

@@ -0,0 +1,80 @@
+/**
+ * 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
+ */
+import type { BusinessLogicError } from '@explorins/pers-shared';
+export declare class ErrorUtils {
+    /**
+     * Fast token expiration detection
+     */
+    static isTokenExpired(error: unknown): boolean;
+    /**
+     * Fast error message extraction
+     */
+    static getMessage(error: unknown): string;
+    /**
+     * Fast status code extraction
+     */
+    static getStatus(error: unknown): number | null;
+    /**
+     * Fast retryability check
+     */
+    static isRetryable(error: unknown): boolean;
+    /**
+     * Check if error is from PERS API (uses @explorins/pers-shared format)
+     */
+    static isPersApiError(error: unknown): error is BusinessLogicError;
+}
+export declare class TokenRefreshNeeded extends Error {
+    refreshToken: string;
+    readonly errorCode = "TOKEN_REFRESH_NEEDED";
+    readonly domain = "auth";
+    readonly category = "SECURITY";
+    readonly retryable = true;
+    constructor(refreshToken: string);
+}
+export declare class ProviderTokenRefreshNeeded extends Error {
+    providerToken: string;
+    readonly errorCode = "PROVIDER_TOKEN_REFRESH_NEEDED";
+    readonly domain = "auth";
+    readonly category = "SECURITY";
+    readonly retryable = true;
+    constructor(providerToken: string);
+}
+export declare class LogoutRequired extends Error {
+    readonly errorCode = "LOGOUT_REQUIRED";
+    readonly domain = "auth";
+    readonly category = "SECURITY";
+    readonly retryable = false;
+    constructor(message: string);
+}
+export declare class PersApiError extends Error {
+    endpoint: string;
+    method: string;
+    status?: number | undefined;
+    readonly errorCode = "PERS_API_ERROR";
+    readonly domain = "api";
+    readonly category = "TECHNICAL";
+    readonly retryable: boolean;
+    constructor(message: string, endpoint: string, method: string, status?: number | undefined, retryable?: boolean);
+}
+export declare class NetworkError extends Error {
+    readonly errorCode = "NETWORK_ERROR";
+    readonly domain = "api";
+    readonly category = "INFRASTRUCTURE";
+    readonly retryable = true;
+    constructor(message: string);
+}
+export declare const PlatformErrorUtils: {
+    isTokenExpiredError: (error: unknown) => boolean;
+    extractErrorMessage: (error: unknown) => string;
+};
+export declare const ApiErrorDetector: {
+    getErrorMessage: (error: unknown) => string;
+    getStatusCode: (error: unknown) => number | null;
+    isRetryable: (error: unknown) => boolean;
+    isAuthError: (error: unknown) => boolean;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/core/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGjE,qBAAa,UAAU;IAErB;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAW9C;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAOzC;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAM/C;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAY3C;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB;CAInE;AAGD,qBAAa,kBAAmB,SAAQ,KAAK;IAMxB,YAAY,EAAE,MAAM;IALvC,QAAQ,CAAC,SAAS,0BAA0B;IAC5C,QAAQ,CAAC,MAAM,UAAU;IACzB,QAAQ,CAAC,QAAQ,cAAc;IAC/B,QAAQ,CAAC,SAAS,QAAQ;gBAEP,YAAY,EAAE,MAAM;CAIxC;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IAMhC,aAAa,EAAE,MAAM;IALxC,QAAQ,CAAC,SAAS,mCAAmC;IACrD,QAAQ,CAAC,MAAM,UAAU;IACzB,QAAQ,CAAC,QAAQ,cAAc;IAC/B,QAAQ,CAAC,SAAS,QAAQ;gBAEP,aAAa,EAAE,MAAM;CAIzC;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,SAAS,qBAAqB;IACvC,QAAQ,CAAC,MAAM,UAAU;IACzB,QAAQ,CAAC,QAAQ,cAAc;IAC/B,QAAQ,CAAC,SAAS,SAAS;gBAEf,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,YAAa,SAAQ,KAAK;IAQ5B,QAAQ,EAAE,MAAM;IAChB,MAAM,EAAE,MAAM;IACd,MAAM,CAAC,EAAE,MAAM;IATxB,QAAQ,CAAC,SAAS,oBAAoB;IACtC,QAAQ,CAAC,MAAM,SAAS;IACxB,QAAQ,CAAC,QAAQ,eAAe;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAG1B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,YAAA,EACtB,SAAS,GAAE,OAAe;CAM7B;AAED,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,SAAS,mBAAmB;IACrC,QAAQ,CAAC,MAAM,SAAS;IACxB,QAAQ,CAAC,QAAQ,oBAAoB;IACrC,QAAQ,CAAC,SAAS,QAAQ;gBAEd,OAAO,EAAE,MAAM;CAI5B;AAGD,eAAO,MAAM,kBAAkB;iCACA,OAAO;iCACP,OAAO;CACrC,CAAC;AAEF,eAAO,MAAM,gBAAgB;6BACF,OAAO;2BACT,OAAO;yBACT,OAAO;yBACP,OAAO;CAK7B,CAAC"}

package/dist/core/index.d.ts

@@ -6,7 +6,8 @@
 export * from './pers-api-client';
 export * from './pers-config';
 export type { PersEnvironment, PersApiVersion } from './pers-config';
-export * from './auth';
+export type { PersAuthProvider } from './auth/auth-provider.interface';
+export * from './environment';
 export * from './abstractions/http-client';
 export { PersSDK, createPersSDK } from '../pers-sdk';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,mBAAmB,CAAC;AAGlC,cAAc,eAAe,CAAC;AAC9B,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGrE,cAAc,QAAQ,CAAC;AAGvB,cAAc,4BAA4B,CAAC;AAG3C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,mBAAmB,CAAC;AAGlC,cAAc,eAAe,CAAC;AAC9B,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAErE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGvE,cAAc,eAAe,CAAC;AAM9B,cAAc,4BAA4B,CAAC;AAG3C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/core/pers-api-client.d.ts

@@ -1,5 +1,29 @@
 /**
  * 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');
+ * ```
  */
 import { HttpClient } from './abstractions/http-client';
 import { PersConfig, mergeWithDefaults } from './pers-config';
@@ -11,7 +35,24 @@ export declare class PersApiClient {
     private readonly mergedConfig;
     private readonly authApi;
     private readonly authService;
+    /**
+     * Creates a new PERS API Client instance
+     *
+     * @param httpClient - Platform-specific HTTP client implementation
+     * @param config - Configuration options for the API client
+     */
     constructor(httpClient: HttpClient, config: PersConfig);
+    /**
+     * 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
+     */
+    private ensureValidToken;
     /**
      * Get request headers including auth token and project key
      */
@@ -21,13 +62,42 @@ export declare class PersApiClient {
      */
     private request;
     /**
-     * Generic GET request
+     * Delegate token refresh to auth provider and handle the results
+     */
+    private handleTokenRefreshDelegation;
+    /**
+     * 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');
+     * ```
      */
     get<T>(endpoint: string, responseType?: 'json' | 'blob' | 'text' | 'arraybuffer'): Promise<T>;
     /**
-     * Generic POST request
+     * 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 });
+     * ```
      */
-    post<T>(endpoint: string, body?: unknown): Promise<T>;
+    post<T>(endpoint: string, body?: unknown, options?: {
+        bypassAuth?: boolean;
+    }): Promise<T>;
     /**
      * Generic PUT request
      */
@@ -37,27 +107,128 @@ export declare class PersApiClient {
      */
     delete<T>(endpoint: string): Promise<T>;
     /**
-     * Login admin user with external JWT (e.g., Firebase)
-     * Automatically stores tokens in auth provider if available
+   * Get request headers WITHOUT auth token (for auth operations like refresh/login)
+   */
+    private getHeadersWithoutAuth;
+    /**
+     * 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);
+     * ```
      */
     loginAdmin(externalJwt: string): Promise<SessionAuthContextResponseDTO>;
     /**
-     * Login regular user with external JWT
-     * Automatically stores tokens in auth provider if available
+     * 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);
+     * ```
      */
     loginUser(externalJwt: string): Promise<SessionAuthContextResponseDTO>;
     /**
-     * Refresh access token using stored refresh token
+     * Authenticates a user using raw login data (no external JWT)
+     *
+     * Useful for custom authentication flows where user data is provided directly.
+     * Automatically stores received tokens for subsequent requests.
+     *
+     * @param rawLoginData - Object containing user login data (email, name, etc.)
+     * @return Promise resolving to session context with user permissions
      */
-    refreshToken(): Promise<SessionAuthResponseDTO>;
+    loginUserWithRawData(rawLoginData: {
+        externalId?: string | undefined;
+        email?: string | undefined;
+        firstName?: string | undefined;
+        lastName?: string | undefined;
+        customData?: Record<string, any> | undefined;
+    }): Promise<SessionAuthContextResponseDTO>;
     /**
-     * Clear all stored authentication tokens
+     * 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();
+     * }
+     * ```
      */
-    clearAuth(): Promise<void>;
+    hasValidAuth(): boolean;
     /**
-     * Check if user has valid authentication token
+     * 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
+     * }
+     * ```
      */
-    hasValidAuth(): boolean;
+    isTokenExpired(marginSeconds?: number): Promise<boolean>;
+    /**
+     * 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();
+     * }
+     * ```
+     */
+    areAllTokensExpired(marginSeconds?: number): Promise<boolean>;
+    /**
+     * Refresh access token using stored refresh token
+     *
+     * @param refreshToken - Optional refresh token, uses stored token if not provided
+     * @returns Promise resolving to new auth tokens
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const tokens = await client.refreshTokens();
+     *   console.log('Tokens refreshed successfully');
+     * } catch (error) {
+     *   console.error('Token refresh failed:', error);
+     * }
+     * ```
+     */
+    refreshTokens(refreshToken?: string): Promise<SessionAuthResponseDTO>;
     /**
      * Get current configuration (returns merged config)
      */
@@ -67,10 +238,4 @@ export declare class PersApiClient {
      */
     getOriginalConfig(): PersConfig;
 }
-export declare class PersApiError extends Error {
-    endpoint: string;
-    method: string;
-    statusCode?: number | undefined;
-    constructor(message: string, endpoint: string, method: string, statusCode?: number | undefined);
-}
 //# sourceMappingURL=pers-api-client.d.ts.map

package/dist/core/pers-api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pers-api-client.d.ts","sourceRoot":"","sources":["../../src/core/pers-api-client.ts"],"names":[],"mappings":"AACA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAkB,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,UAAU,EAAgB,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAG5E,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAoB,MAAM,iDAAiD,CAAC;AAG1I,qBAAa,aAAa;IAOtB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,MAAM;IAPhB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuC;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;gBAGhC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,UAAU;IAkB5B;;OAEG;YACW,UAAU;IA2BxB;;OAEG;YACW,OAAO;IAuErB;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC;IAInG;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAI3D;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1D;;OAEG;IACG,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ7C;;;OAGG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAI7E;;;OAGG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAI5E;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAQrD;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,SAAS,IAAI,UAAU,CAAC,OAAO,iBAAiB,CAAC;IAIjD;;OAEG;IACH,iBAAiB,IAAI,UAAU;CAGhC;AAED,qBAAa,YAAa,SAAQ,KAAK;IAG5B,QAAQ,EAAE,MAAM;IAChB,MAAM,EAAE,MAAM;IACd,UAAU,CAAC,EAAE,MAAM;gBAH1B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,YAAA;CAK7B"}
+{"version":3,"file":"pers-api-client.d.ts","sourceRoot":"","sources":["../../src/core/pers-api-client.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAkB,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,UAAU,EAAgB,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAG5E,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAoB,MAAM,iDAAiD,CAAC;AAW1I,qBAAa,aAAa;IAatB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,MAAM;IAbhB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuC;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C;;;;;OAKG;gBAEO,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,UAAU;IAsB5B;;;;;;;;;OASG;YACW,gBAAgB;IAkB9B;;OAEG;YACW,UAAU;IA2BxB;;OAEG;YACW,OAAO;IAqFrB;;OAEG;YACW,4BAA4B;IA8B1C;;;;;;;;;;;;;OAaG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC;IAInG;;;;;;;;;;;;;;OAcG;IACG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAI/F;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1D;;OAEG;IACG,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAI7C;;KAEC;YACW,qBAAqB;IAsBjC;;;;;;;;;;;;;;;OAeG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAI7E;;;;;;;;;;;;;;;OAeG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAI5E;;;;;;;;OAQG;IACG,oBAAoB,CAAC,YAAY,EAAE;QACvC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KAC9C,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAK1C;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,IAAI,OAAO;IAIvB;;;;;;;;;;;;;OAaG;IACG,cAAc,CAAC,aAAa,GAAE,MAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAYlE;;;;;;;;;;;;;;;OAeG;IACG,mBAAmB,CAAC,aAAa,GAAE,MAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IASvE;;;;;;;;;;;;;;;OAeG;IACG,aAAa,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAI3E;;OAEG;IACH,SAAS,IAAI,UAAU,CAAC,OAAO,iBAAiB,CAAC;IAIjD;;OAEG;IACH,iBAAiB,IAAI,UAAU;CAGhC"}

package/dist/core/pers-config.d.ts

@@ -1,16 +1,49 @@
 /**
- * PERS SDK Configuration interfaces
+ * PERS SDK Configuration interfaces and utilities
+ *
+ * Provides type-safe configuration options for the PERS SDK
+ * with sensible defaults for production environments.
  */
 import { PersAuthProvider } from './auth/auth-provider.interface';
+/** PERS API environment targets */
 export type PersEnvironment = 'development' | 'staging' | 'production';
+/** Supported PERS API versions */
 export type PersApiVersion = 'v1' | 'v1.8' | 'v1.9' | 'v2';
+/**
+ * PERS SDK Configuration
+ *
+ * @example
+ * ```typescript
+ * const config: PersConfig = {
+ *   environment: 'production',
+ *   apiProjectKey: 'your-project-key',
+ *   apiVersion: 'v2',
+ *   authProvider: createAuthProvider({
+ *     tokenProvider: () => getFirebaseToken()
+ *   }),
+ *   tokenRefreshMargin: 120,
+ *   timeout: 30000
+ * };
+ * ```
+ */
 export interface PersConfig {
+    /** Target environment (default: 'production') */
     environment?: PersEnvironment;
+    /** Project key for API authentication */
     apiProjectKey?: string;
+    /** API version to use (default: 'v2') */
     apiVersion?: PersApiVersion;
+    /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** Number of retry attempts (default: 3) */
     retries?: number;
+    /** Authentication provider instance */
     authProvider?: PersAuthProvider;
+    /** Seconds before expiry to refresh token proactively (default: 60) */
+    tokenRefreshMargin?: number;
+    /** Seconds threshold for background vs blocking refresh (default: 30) */
+    backgroundRefreshThreshold?: number;
+    /** Internal - API root URL constructed automatically */
     readonly apiRoot?: string;
 }
 export interface PersAuthConfig {
@@ -25,6 +58,8 @@ export declare const DEFAULT_PERS_CONFIG: {
     readonly apiVersion: PersApiVersion;
     readonly timeout: 30000;
     readonly retries: 3;
+    readonly tokenRefreshMargin: 60;
+    readonly backgroundRefreshThreshold: 30;
 };
 /**
  * Internal function to construct API root from environment

package/dist/core/pers-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pers-config.d.ts","sourceRoot":"","sources":["../../src/core/pers-config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;AACvE,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAEhC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,GAAG,KAAK,GAAG,MAAM,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB;0BACD,eAAe;yBACxB,cAAc;;;CAG1B,CAAC;AAEX;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,WAAW,GAAE,eAA8B,EAC3C,OAAO,GAAE,cAAqB,GAC7B,MAAM,CAQR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CASnJ"}
+{"version":3,"file":"pers-config.d.ts","sourceRoot":"","sources":["../../src/core/pers-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,mCAAmC;AACnC,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;AAEvE,kCAAkC;AAClC,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAE9B,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,yCAAyC;IACzC,UAAU,CAAC,EAAE,cAAc,CAAC;IAE5B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAEhC,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,yEAAyE;IACzE,0BAA0B,CAAC,EAAE,MAAM,CAAC;IAEpC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,GAAG,KAAK,GAAG,MAAM,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB;0BACD,eAAe;yBACxB,cAAc;;;;;CAK1B,CAAC;AAEX;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,WAAW,GAAE,eAA8B,EAC3C,OAAO,GAAE,cAAqB,GAC7B,MAAM,CAQR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,CAAC,CASnJ"}

package/dist/core/utils/jwt.function.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.function.d.ts","sourceRoot":"","sources":["../../../src/core/utils/jwt.function.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,SAAQ,MAAW,KAAG,OAoBnE,CAAC"}
+{"version":3,"file":"jwt.function.d.ts","sourceRoot":"","sources":["../../../src/core/utils/jwt.function.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,SAAQ,MAAW,KAAG,OAmBnE,CAAC"}