@explorins/pers-sdk 1.2.6 → 1.3.1

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

@@ -1,9 +1,33 @@
 /**
  * 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';
-import { SessionAuthResponseDTO, SessionAuthContextResponseDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
+import { SessionAuthContextResponseDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
 export declare class PersApiClient {
     private httpClient;
     private 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,101 @@ 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
      */
-    refreshToken(): Promise<SessionAuthResponseDTO>;
     /**
      * Clear all stored authentication tokens
      */
-    clearAuth(): Promise<void>;
     /**
-     * Check if user has valid authentication token
+     * 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(): boolean;
+    /**
+     * 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
+     * }
+     * ```
+     */
+    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>;
     /**
      * Get current configuration (returns merged config)
      */
@@ -67,10 +211,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,EAA0B,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;;OAEG;IASH;;OAEG;IAKH;;;;;;;;;;;;;;;;;;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;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"}