@mussnad/frappe-js-client/dist/utils/axios.d.ts

Next-generation TS/JS client for Frappe REST APIs, built on axios for robust, type-safe integration.

/**
 * @module utils/axios
 * @description Provides utility functions for creating and configuring Axios instances
 * with Frappe-specific headers and authentication. This module handles CSRF token management,
 * site name headers, and authentication token configuration for API requests.
 *
 * @packageDocumentation
 * @preferred
 *
 * @example
 * ```typescript
 * import { getAxiosClient } from '@frappe/axios'
 *
 * // Create a client with Bearer token authentication
 * const client = getAxiosClient(
 *   'https://api.example.com',
 *   true,
 *   () => 'your-token',
 *   'Bearer'
 * );
 *
 * // Create a client without authentication
 * const basicClient = getAxiosClient('https://api.example.com');
 * ```
 */
import { AxiosInstance, AxiosRequestConfig, RawAxiosRequestHeaders } from 'axios';
/**
 * Creates and configures an Axios instance with Frappe-specific settings.
 *
 * @param appURL - The base URL for API requests
 * @param useToken - Optional flag to enable token-based authentication
 * @param token - Optional function that returns the authentication token
 * @param tokenType - Optional token type, either 'Bearer' or 'token'
 * @param customHeaders - Optional additional headers to include in requests
 *
 * @returns An configured Axios instance
 *
 * @example
 * ```typescript
 * // Basic usage without authentication
 * const client = getAxiosClient('https://instance.example.com');
 *
 * // With Bearer token authentication
 * const authenticatedClient = getAxiosClient(
 *   'https://instance.example.com',
 *   true,
 *   () => localStorage.getItem('token'),
 *   'Bearer'
 * );
 *
 * // With custom headers
 * const clientWithHeaders = getAxiosClient(
 *   'https://instance.example.com',
 *   false,
 *   undefined,
 *   undefined,
 *   { 'Custom-Header': 'value' }
 * );
 * ```
 */
export declare function getAxiosClient(appURL: string, useToken?: boolean, token?: () => string, tokenType?: 'Bearer' | 'token', customHeaders?: object): AxiosInstance;
/**
 * Generates request headers for Frappe API requests.
 *
 * @param useToken - Whether to include authentication token in headers
 * @param tokenType - The type of authentication token ('Bearer' or 'token')
 * @param token - Function that returns the authentication token
 * @param appURL - The base URL of the application
 * @param customHeaders - Additional custom headers to include
 *
 * @returns An object containing the configured request headers
 *
 * @remarks
 * This function automatically handles:
 * - Content-Type and Accept headers for JSON
 * - Authentication token headers when specified
 * - Frappe-specific headers (X-Frappe-Site-Name)
 * - CSRF token headers in browser environments
 *
 * @example
 * ```typescript
 * const headers = getRequestHeaders(
 *   true,
 *   'Bearer',
 *   () => 'your-token',
 *   'https://instance.example.com',
 *   { 'Custom-Header': 'value' }
 * );
 * ```
 *
 * @internal
 */
export declare function getRequestHeaders(useToken?: boolean, tokenType?: 'Bearer' | 'token', token?: () => string, appURL?: string, customHeaders?: object): RawAxiosRequestHeaders;
export declare function getCSRFToken(): string | undefined;
/**
 * Interface for the request handler options
 */
export interface RequestHandlerOptions<T = any, R = any> {
    /** The axios instance to use for the request */
    axios: AxiosInstance;
    /** The request configuration */
    config: AxiosRequestConfig;
    /** Optional error message to use when request fails */
    errorMessage?: string;
    /** Optional function to transform the response data */
    transformResponse?: (response: T) => R;
}
/**
 * Handles a request and returns the transformed response data.
 *
 * @param axios - The axios instance to use for the request
 * @param config - The request configuration
 * @param errorMessage - Optional error message to use when request fails
 * @param transformResponse - Optional function to transform the response data
 * @returns The transformed response data
 *
 * @example
 * ```typescript
 * const response = await handleRequest({
 *   axios,
 *   config,
 *   errorMessage: 'An error occurred while processing the request.',
 *   transformResponse: (data: T): R => data as any as R,
 * });
 * ```
 */
export declare function handleRequest<T = any, R = T>({ axios, config, errorMessage, transformResponse, }: RequestHandlerOptions<T, R>): Promise<R>;
/**
 * Extracts the site name from the appURL.
 *
 * @param appURL - The base URL of the application
 * @returns The site name
 */
export declare function getSiteName(appURL: string | undefined): string | undefined;