@pagamio/frontend-commons-lib 0.8.175 → 0.8.183

package/lib/api/swr.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview SWR integration for the API client
+ */
+import useSWR, { mutate } from 'swr';
+import { useApi } from './context';
+// Default SWR configuration
+const DEFAULT_SWR_CONFIG = {
+    revalidateOnFocus: false,
+    revalidateOnReconnect: false,
+    shouldRetryOnError: true,
+    errorRetryInterval: 10000,
+    // Increase to prevent new requests on same resources
+    dedupingInterval: 300000, // 5 minutes
+    revalidateIfStale: false,
+    revalidateOnMount: true,
+    // Prevent automatic polling
+    refreshInterval: 0,
+    refreshWhenHidden: false,
+    refreshWhenOffline: false,
+    // Use stale data by default to reduce server load
+    keepPreviousData: true,
+    focusThrottleInterval: 60000,
+};
+/**
+ * Creates a fetcher function using the existing ApiClient
+ * @template ResponseData - Expected response type
+ */
+const createApiFetcher = () => {
+    const api = useApi();
+    return async (key, config) => {
+        const url = Array.isArray(key) ? key[0] : key;
+        if (typeof url !== 'string') {
+            throw new Error('Only string keys are supported');
+        }
+        // Handle different HTTP methods
+        switch (config?.method) {
+            case 'POST':
+                return api.post(url, config.body ? JSON.parse(config.body.toString()) : undefined, { ...config });
+            case 'PUT':
+                return api.put(url, config.body ? JSON.parse(config.body.toString()) : undefined, { ...config });
+            case 'PATCH':
+                return api.patch(url, config.body ? JSON.parse(config.body.toString()) : undefined, {
+                    ...config,
+                });
+            case 'DELETE':
+                return api.delete(url, { ...config });
+            default:
+                return api.get(url, { ...config });
+        }
+    };
+};
+/**
+ * Main SWR hook that automatically inherits auth config
+ * @template ResponseData - Type of the expected response data
+ * @template ErrorData - Type of the error response (defaults to ApiErrorResponse)
+ */
+export function useApiSWR(endpoint, config) {
+    const fetcher = createApiFetcher();
+    const { params, skipAuth, skipRetry, skipRefresh, isProtected, 
+    // Extract SWR-specific config
+    ...swrConfig } = config || {};
+    const requestConfig = {
+        params,
+        skipAuth,
+        skipRetry,
+        skipRefresh,
+        isProtected,
+    };
+    const mergedConfig = {
+        ...DEFAULT_SWR_CONFIG,
+        ...swrConfig,
+    };
+    return useSWR(endpoint, (url) => fetcher(url, { ...requestConfig, ...config }), mergedConfig);
+}
+/**
+ * Paginated SWR hook that inherits auth config
+ * @template ItemType - Type of items in the paginated response
+ * @template ResponseType - Type of the full response (defaults to SpringBootResponse)
+ */
+export function usePaginatedApiSWR(endpoint, config) {
+    return useApiSWR(endpoint, config);
+}
+/**
+ * Mutation hook that inherits auth config
+ * @template ResponseData - Type of the expected response data
+ */
+export function useApiMutation() {
+    const api = useApi();
+    return {
+        post: async (endpoint, data, config) => {
+            const response = await api.post(endpoint, data, config);
+            await mutate(endpoint, response, false);
+            return response;
+        },
+        put: async (endpoint, data, config) => {
+            const response = await api.put(endpoint, data, config);
+            await mutate(endpoint, response, false);
+            return response;
+        },
+        patch: async (endpoint, data, config) => {
+            const response = await api.patch(endpoint, data, config);
+            await mutate(endpoint, response, false);
+            return response;
+        },
+        delete: async (endpoint, config) => {
+            const response = await api.delete(endpoint, config);
+            await mutate(endpoint, null, false);
+            return response;
+        },
+    };
+}
+/**
+ * Combined SWR and mutation hook
+ * @template ResponseData - Type of the expected response data
+ */
+export function useApiSWRWithMutation(endpoint, config) {
+    const swr = useApiSWR(endpoint, config);
+    const mutation = useApiMutation();
+    return {
+        ...swr,
+        mutate: mutation,
+        refresh: () => mutate(endpoint),
+    };
+}

package/lib/api/types.d.ts

@@ -0,0 +1,145 @@
+import type { CustomAuthConfig, TokenManager } from '../auth';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface ApiErrorResponse {
+    error?: string;
+    message?: string;
+    status?: number;
+    [key: string]: unknown;
+}
+export declare class ApiError extends Error {
+    status: number;
+    data?: unknown;
+    constructor(message: string, status: number, data?: unknown);
+}
+export interface ApiClientConfig<T extends CustomAuthConfig> {
+    baseURL: string;
+    tokenManager?: TokenManager<T>;
+    defaultHeaders?: HeadersInit;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+    onRequest?: (config: RequestInit) => Promise<RequestInit> | RequestInit;
+    onResponse?: <T>(response: Response, data: T) => Promise<T> | T;
+    onError?: (error: ApiError) => Promise<void> | void;
+    onUnauthorized?: () => Promise<void> | void;
+}
+export interface RequestConfig extends RequestInit {
+    params?: Record<string, string>;
+    timeout?: number;
+    retries?: number;
+    skipAuth?: boolean;
+    skipRetry?: boolean;
+    skipRefresh?: boolean;
+    isProtected?: boolean;
+    signal?: AbortSignal | null;
+}
+/**
+ * Spring Boot style paginated response interface
+ */
+export interface SpringBootResponse<T> {
+    content: T[];
+    pageable: {
+        sort: {
+            empty: boolean;
+            sorted: boolean;
+            unsorted: boolean;
+        };
+        offset: number;
+        pageNumber: number;
+        pageSize: number;
+        paged: boolean;
+        unpaged: boolean;
+    };
+    totalElements: number;
+    totalPages: number;
+    last: boolean;
+    size: number;
+    number: number;
+    sort: {
+        empty: boolean;
+        sorted: boolean;
+        unsorted: boolean;
+    };
+    first: boolean;
+    numberOfElements: number;
+    empty: boolean;
+}
+/**
+ * Configuration for mapping API response structure
+ */
+export interface ResponseMapping {
+    /** Path to data array in response (e.g., 'content' or 'data.items') */
+    data?: string;
+    /** Path to total count (e.g., 'totalElements' or 'meta.total') */
+    total?: string;
+    /** Path to current page number */
+    page?: string;
+    /** Path to page size */
+    pageSize?: string;
+    /** Default values when paths are not found */
+    defaultValues?: {
+        data: any[];
+        total: number;
+        page: number;
+        pageSize: number;
+    };
+    /** Type of response structure */
+    responseType?: 'default' | 'spring-boot';
+}
+/**
+ * Configuration for query parameter formatting
+ */
+export interface QueryParamConfig {
+    pagination?: {
+        /** Parameter name for page number (default: 'page') */
+        pageParam?: string;
+        /** Parameter name for page size (default: 'size') */
+        sizeParam?: string;
+        /** Custom transform function for pagination parameters */
+        transform?: (page: number, size: number) => Record<string, string>;
+    };
+    sorting?: {
+        /** Parameter name for sort field (default: 'sortBy') */
+        sortByParam?: string;
+        /** Parameter name for sort direction (default: 'sortDir') */
+        sortDirParam?: string;
+        /** Custom transform function for sorting parameters */
+        transform?: (sortBy: string, sortDir: string) => Record<string, string>;
+    };
+    filtering?: {
+        /** Parameter name for search query (default: 'searchQuery') */
+        searchParam?: string;
+        /** Format for filter parameters */
+        filterFormat?: 'bracket' | 'flat' | 'prefix' | 'custom';
+        /** Prefix for filter parameters when using 'prefix' format */
+        filterPrefix?: string;
+        /** Custom transform function for filter parameters */
+        transform?: (filters: Record<string, string>) => Record<string, string>;
+    };
+}
+/**
+ * Represents a single mock configuration for an API request.
+ */
+export interface MockConfig {
+    /**
+     * The path of the API endpoint (e.g., "/dashboard/metrics").
+     */
+    path: string;
+    /**
+     * The HTTP method (e.g., "GET", "POST", "PUT", "DELETE").
+     */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /**
+     * The query parameters or payload expected in the request.
+     * If undefined, the mock will match any request to the path and method.
+     */
+    params?: Record<string, any> | any[];
+    /**
+     * The mock response to return when the request matches.
+     */
+    response: any;
+}
+/**
+ * Type for the `mockConfig` prop, which is an array of `MockConfig` objects.
+ */
+export type MockConfigArray = MockConfig[];

package/lib/api/types.js

@@ -0,0 +1,10 @@
+export class ApiError extends Error {
+    status;
+    data;
+    constructor(message, status, data) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.data = data;
+    }
+}

package/lib/auth/authenticators/AuthenticatorFactory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Factory for creating authenticator processors
+ * Provides a central registry for different authentication processors
+ */
+import type { CustomAuthConfig } from '../types';
+import { type AuthenticatorProcessor, AuthenticatorType } from './types';
+/**
+ * Factory class for creating authenticator processors
+ * Maintains a registry of processor implementations and creates instances on demand
+ */
+export declare class AuthenticatorFactory {
+    private static processors;
+    /**
+     * Gets an authenticator processor by type
+     * @param type - The type of authenticator to get
+     * @returns An authenticator processor instance
+     */
+    static getProcessor<T extends CustomAuthConfig>(type?: AuthenticatorType | string): AuthenticatorProcessor<T>;
+    /**
+     * Registers a new authenticator processor
+     * @param type - The type identifier for this processor
+     * @param processorClass - The processor class constructor
+     */
+    static registerProcessor(type: string, processorClass: new <T extends CustomAuthConfig>() => AuthenticatorProcessor<T>): void;
+}

package/lib/auth/authenticators/AuthenticatorFactory.js

@@ -0,0 +1,32 @@
+import { DefaultAuthenticatorProcessor } from './processors/DefaultAuthenticatorProcessor';
+import { StrapiAuthenticatorProcessor } from './processors/StrapiAuthenticatorProcessor';
+import { AuthenticatorType } from './types';
+/**
+ * Factory class for creating authenticator processors
+ * Maintains a registry of processor implementations and creates instances on demand
+ */
+export class AuthenticatorFactory {
+    // Registry of authenticator processor constructors
+    static processors = {
+        [AuthenticatorType.DEFAULT]: DefaultAuthenticatorProcessor,
+        [AuthenticatorType.STRAPI]: StrapiAuthenticatorProcessor,
+    };
+    /**
+     * Gets an authenticator processor by type
+     * @param type - The type of authenticator to get
+     * @returns An authenticator processor instance
+     */
+    static getProcessor(type) {
+        // If no type specified or type not found, return the default processor
+        const ProcessorClass = type && this.processors[type] ? this.processors[type] : this.processors[AuthenticatorType.DEFAULT];
+        return new ProcessorClass();
+    }
+    /**
+     * Registers a new authenticator processor
+     * @param type - The type identifier for this processor
+     * @param processorClass - The processor class constructor
+     */
+    static registerProcessor(type, processorClass) {
+        this.processors[type] = processorClass;
+    }
+}

package/lib/auth/authenticators/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Exports all authenticator-related components
+ */
+export * from './types';
+export * from './AuthenticatorFactory';
+export * from './processors/DefaultAuthenticatorProcessor';
+export * from './processors/StrapiAuthenticatorProcessor';

package/lib/auth/authenticators/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Exports all authenticator-related components
+ */
+export * from './types';
+export * from './AuthenticatorFactory';
+export * from './processors/DefaultAuthenticatorProcessor';
+export * from './processors/StrapiAuthenticatorProcessor';

package/lib/auth/authenticators/processors/DefaultAuthenticatorProcessor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Default authenticator processor implementation
+ * Handles standard authentication flows without special transformations
+ */
+import type { AuthResponse, CustomAuthConfig } from '../../types';
+import type { AuthenticatorProcessor } from '../types';
+/**
+ * Default authenticator processor
+ * Handles the standard authentication process with basic validation
+ * @template T - Type extending CustomAuthConfig
+ */
+export declare class DefaultAuthenticatorProcessor<T extends CustomAuthConfig> implements AuthenticatorProcessor<T> {
+    /**
+     * Process login credentials using the standard authentication flow
+     * @param credentials - User login credentials
+     * @param rememberMe - Whether to remember the user session
+     * @param login - The login function from auth context
+     * @returns Promise resolving to authentication response
+     */
+    processLogin(credentials: Record<string, unknown>, rememberMe: boolean, login: (credentials: T['Credentials'], rememberMe: boolean) => Promise<AuthResponse<T>>): Promise<AuthResponse<T>>;
+}

package/lib/auth/authenticators/processors/DefaultAuthenticatorProcessor.js

@@ -0,0 +1,26 @@
+/**
+ * Default authenticator processor
+ * Handles the standard authentication process with basic validation
+ * @template T - Type extending CustomAuthConfig
+ */
+export class DefaultAuthenticatorProcessor {
+    /**
+     * Process login credentials using the standard authentication flow
+     * @param credentials - User login credentials
+     * @param rememberMe - Whether to remember the user session
+     * @param login - The login function from auth context
+     * @returns Promise resolving to authentication response
+     */
+    async processLogin(credentials, rememberMe, login) {
+        // Validate the credentials to ensure required fields are present
+        if (!credentials || typeof credentials !== 'object') {
+            throw new Error('Invalid login data: Credentials must be an object');
+        }
+        const requiredKeys = Object.keys(credentials);
+        if (requiredKeys.length === 0) {
+            throw new Error('Invalid login data: No credentials provided');
+        }
+        // Use type assertion to satisfy the login function parameter type
+        return login(credentials, rememberMe);
+    }
+}

package/lib/auth/authenticators/processors/StrapiAuthenticatorProcessor.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Strapi authenticator processor implementation
+ * Handles Strapi-specific authentication flows
+ */
+import type { AuthResponse, CustomAuthConfig } from '../../types';
+import type { AuthenticatorProcessor } from '../types';
+/**
+ * Strapi user structure
+ */
+export interface StrapiUser {
+    id: number;
+    documentId: string;
+    username: string;
+    email: string;
+    provider: string;
+    confirmed: boolean;
+    blocked: boolean;
+    createdAt: string;
+    updatedAt: string;
+    publishedAt: string;
+    firstName: string;
+    lastName: string;
+    company: string;
+    isFirstTimeLogin: boolean;
+    hasCompletedOnboarding: boolean;
+    hasSkippedOnboarding: boolean;
+    onBoardingReminderTime: string;
+    loginCount: number;
+    lastLoginAt: string;
+    role: {
+        id: number;
+        documentId: string;
+        name: string;
+        description: string;
+        type: string;
+        createdAt: string;
+        updatedAt: string;
+        publishedAt: string;
+    };
+}
+/**
+ * Strapi authentication response structure
+ */
+export interface StrapiAuthResponse {
+    jwt: string;
+    user: StrapiUser;
+}
+/**
+ * Transforms a valid Strapi response into our application's auth response format
+ * @param strapiResponse - Validated Strapi auth response
+ * @returns Transformed auth response
+ */
+export declare function transformStrapiResponse<T extends CustomAuthConfig>(strapiResponse: StrapiAuthResponse): AuthResponse<T>;
+/**
+ * Validates if the response is a valid Strapi authentication response
+ * @param response - API response to validate
+ * @returns Boolean indicating if response is a valid Strapi auth response
+ */
+export declare function isStrapiAuthResponse(response: unknown): response is StrapiAuthResponse;
+/**
+ * Strapi authenticator processor
+ * Handles authentication process specific to Strapi backend
+ * @template T - Type extending CustomAuthConfig
+ */
+export declare class StrapiAuthenticatorProcessor<T extends CustomAuthConfig> implements AuthenticatorProcessor<T> {
+    /**
+     * Process login credentials using the Strapi authentication flow
+     * @param credentials - User login credentials
+     * @param rememberMe - Whether to remember the user session
+     * @param login - The login function from auth context
+     * @returns Promise resolving to authentication response
+     */
+    processLogin(credentials: Record<string, unknown>, rememberMe: boolean, login: (credentials: T['Credentials'], rememberMe: boolean) => Promise<AuthResponse<T>>): Promise<AuthResponse<T>>;
+}

package/lib/auth/authenticators/processors/StrapiAuthenticatorProcessor.js

@@ -0,0 +1,99 @@
+/**
+ * Transforms a valid Strapi response into our application's auth response format
+ * @param strapiResponse - Validated Strapi auth response
+ * @returns Transformed auth response
+ */
+export function transformStrapiResponse(strapiResponse) {
+    // Create a new user object that conforms to T['UserInfo']
+    // This approach avoids direct type assertion of the entire object
+    const userInfo = {
+        id: strapiResponse.user.id,
+        userName: strapiResponse.user.username,
+        firstName: strapiResponse.user.firstName,
+        lastName: strapiResponse.user.lastName,
+        email: strapiResponse.user.email,
+        blocked: strapiResponse.user.blocked,
+        company: strapiResponse.user.company,
+        isFirstTimeLogin: strapiResponse.user.isFirstTimeLogin,
+        hasCompletedOnboarding: strapiResponse.user.hasCompletedOnboarding,
+        hasSkippedOnboarding: strapiResponse.user.hasSkippedOnboarding,
+        onBoardingReminderTime: strapiResponse.user.onBoardingReminderTime,
+        loginCount: strapiResponse.user.loginCount,
+        roleName: strapiResponse.user.role.name,
+        roleCode: strapiResponse.user.role.type,
+    };
+    return {
+        user: userInfo,
+        auth: {
+            accessToken: {
+                token: strapiResponse.jwt,
+                expiresIn: 36000000, // Default to 10 hours if not provided
+            },
+        },
+    };
+}
+/**
+ * Validates if the response is a valid Strapi authentication response
+ * @param response - API response to validate
+ * @returns Boolean indicating if response is a valid Strapi auth response
+ */
+export function isStrapiAuthResponse(response) {
+    if (!response || typeof response !== 'object') {
+        return false;
+    }
+    const potentialStrapiResponse = response;
+    // Check if jwt exists and is a non-empty string
+    if (typeof potentialStrapiResponse.jwt !== 'string' || potentialStrapiResponse.jwt.trim() === '') {
+        return false;
+    }
+    // Check if user exists and is an object
+    if (!potentialStrapiResponse.user || typeof potentialStrapiResponse.user !== 'object') {
+        return false;
+    }
+    // Optional: Add additional validation for critical user properties
+    // For example, check if required user fields are present
+    const user = potentialStrapiResponse.user;
+    if (typeof user.id !== 'number' || typeof user.email !== 'string' || user.email?.trim() === '') {
+        return false;
+    }
+    return true;
+}
+/**
+ * Strapi authenticator processor
+ * Handles authentication process specific to Strapi backend
+ * @template T - Type extending CustomAuthConfig
+ */
+export class StrapiAuthenticatorProcessor {
+    /**
+     * Process login credentials using the Strapi authentication flow
+     * @param credentials - User login credentials
+     * @param rememberMe - Whether to remember the user session
+     * @param login - The login function from auth context
+     * @returns Promise resolving to authentication response
+     */
+    async processLogin(credentials, rememberMe, login) {
+        // Strapi typically expects credentials in identifier/password format
+        // Adapt the credentials if needed for Strapi API
+        const strapiCredentials = {};
+        // If username is provided, map it to identifier
+        if ('username' in credentials) {
+            strapiCredentials.identifier = credentials.username;
+        }
+        // Copy the password
+        if ('password' in credentials) {
+            strapiCredentials.password = credentials.password;
+        }
+        // Copy any additional fields
+        Object.entries(credentials).forEach(([key, value]) => {
+            if (key !== 'username' && !strapiCredentials[key]) {
+                strapiCredentials[key] = value;
+            }
+        });
+        // Validate the credentials
+        if (!strapiCredentials.identifier || !strapiCredentials.password) {
+            throw new Error('Invalid Strapi login data: identifier and password are required');
+        }
+        // Use type assertion to satisfy the login function parameter type
+        return login(strapiCredentials, rememberMe);
+    }
+}

package/lib/auth/authenticators/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Defines interfaces for authentication processors
+ * Provides type definitions for the authenticator factory pattern
+ */
+import type { AuthResponse, CustomAuthConfig } from '../types';
+/**
+ * Interface for authentication processor
+ * Defines the contract that all authentication processors must implement
+ */
+export interface AuthenticatorProcessor<T extends CustomAuthConfig> {
+    /**
+     * Process login credentials and authenticate with the appropriate service
+     * @param credentials - User login credentials
+     * @param rememberMe - Whether to remember the user session
+     * @param login - The login function from auth context
+     * @returns Promise resolving to authentication response
+     */
+    processLogin(credentials: Record<string, unknown>, rememberMe: boolean, login: (credentials: T['Credentials'], rememberMe: boolean) => Promise<AuthResponse<T>>): Promise<AuthResponse<T>>;
+}
+/**
+ * Types of authenticators supported by the system
+ */
+export declare enum AuthenticatorType {
+    DEFAULT = "default",
+    STRAPI = "strapi"
+}

package/lib/auth/authenticators/types.js

@@ -0,0 +1,9 @@
+/**
+ * Types of authenticators supported by the system
+ */
+export var AuthenticatorType;
+(function (AuthenticatorType) {
+    AuthenticatorType["DEFAULT"] = "default";
+    AuthenticatorType["STRAPI"] = "strapi";
+    // Add more authenticator types as needed
+})(AuthenticatorType || (AuthenticatorType = {}));

package/lib/auth/components/AppBanner.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface AppBannerProps {
+    text?: string;
+    backgroundColor?: string;
+}
+declare const AppBanner: React.FC<AppBannerProps>;
+export default AppBanner;

package/lib/auth/components/AppBanner.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+const AppBanner = ({ text = 'EVENTS!', backgroundColor = '#b45dae' }) => {
+    return (_jsx("div", { className: "flex w-full justify-end mr-[29%] mt-[-7%]", children: _jsx("div", { className: "inline-block px-6 py-2 text-white font-bold uppercase text-[15px] relative bg-primary-500", style: {
+                // backgroundColor: backgroundColor,
+                // This clip-path creates the right arrow shape
+                clipPath: 'polygon(14% 18%, 85% 18%, 97% 51%, 85% 85%, 14% 85%)',
+            }, children: text }) }));
+};
+export default AppBanner;

package/lib/auth/components/AuthCard.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+interface AuthCardProps {
+    children: ReactNode;
+    className?: string;
+    horizontal?: boolean;
+}
+export declare function AuthCard({ children, className, horizontal }: Readonly<AuthCardProps>): import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/auth/components/AuthCard.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Card } from 'flowbite-react';
+export function AuthCard({ children, className = '', horizontal = true }) {
+    return (_jsx(Card, { horizontal: horizontal, className: `w-full ${className}`, theme: {
+            root: {
+                children: 'my-auto w-full gap-0 space-y-6 p-4 sm:p-6 lg:p-8',
+            },
+            img: {
+                horizontal: {
+                    on: 'hidden w-2/3 rounded-l-lg md:w-96 md:p-0 lg:block',
+                },
+            },
+        }, children: children }));
+}