@tapsilat/tapsilat-js 1.0.3 → 1.0.4

package/dist/http/HttpClient.d.ts

@@ -1,7 +1,14 @@
-import { TapsilatConfig, APIResponse } from "../types";
+/**
+ * @category HTTP
+ * @module HttpClient
+ */
+import { TapsilatConfig, APIResponse } from "../types/index";
 import { InterceptorManager } from "./interceptors";
 /**
- * Configuration options for individual HTTP requests
+ * @category HTTP
+ * @summary Configuration options for individual HTTP requests
+ * @description Extends RequestInit with additional Tapsilat-specific options for HTTP requests
+ * @interface RequestConfig
  */
 export interface RequestConfig extends Omit<RequestInit, "method" | "body"> {
     timeout?: number;
@@ -11,16 +18,24 @@ export interface RequestConfig extends Omit<RequestInit, "method" | "body"> {
     params?: Record<string, any>;
 }
 /**
- * HTTP methods supported by the client
+ * @category HTTP
+ * @summary HTTP methods supported by the client
+ * @description The standard HTTP methods available for API requests
+ * @typedef {string} HttpMethod
  */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /**
- * Generic constraint for request body types
+ * @category HTTP
+ * @summary Generic constraint for request body types
+ * @description Types that can be sent as HTTP request bodies
+ * @typedef {object|array|string|FormData} RequestBody
  */
 export type RequestBody = Record<string, unknown> | Record<string, any> | object | unknown[] | string | FormData;
 /**
- * HTTP Client for making API requests with comprehensive error handling,
- * retry logic, and request/response interceptors
+ * @category HTTP
+ * @summary HTTP Client for making API requests to Tapsilat services
+ * @description Provides a robust client with comprehensive error handling,
+ * retry logic, and request/response interceptors for interacting with the Tapsilat API
  *
  * @example
  * ```typescript
@@ -31,41 +46,55 @@ export type RequestBody = Record<string, unknown> | Record<string, any> | object
  *
  * const data = await client.get<UserResponse>('/users/123');
  * ```
+ * @class HttpClient
  */
 export declare class HttpClient {
     private readonly config;
     private readonly interceptors;
+    /**
+     * @summary Creates a new HTTP client instance
+     * @description Initializes the HTTP client with the provided configuration
+     *
+     * @param config - The configuration for the Tapsilat API client
+     */
     constructor(config: TapsilatConfig);
     /**
-     * GET request method overloads
+     * @summary Performs GET requests to the API
+     * @description Makes HTTP GET requests to retrieve data from the API
      */
     get<T = unknown>(url: string): Promise<APIResponse<T>>;
     get<T = unknown>(url: string, config: RequestConfig): Promise<APIResponse<T>>;
     /**
-     * POST request method overloads
+     * @summary Performs POST requests to the API
+     * @description Makes HTTP POST requests to send data to the API
      */
     post<T = unknown>(url: string): Promise<APIResponse<T>>;
     post<T = unknown>(url: string, body: RequestBody): Promise<APIResponse<T>>;
     post<T = unknown>(url: string, body: RequestBody, config: RequestConfig): Promise<APIResponse<T>>;
     /**
-     * PUT request method overloads
+     * @summary Performs PUT requests to the API
+     * @description Makes HTTP PUT requests to update entire resources in the API
      */
     put<T = unknown>(url: string): Promise<APIResponse<T>>;
     put<T = unknown>(url: string, body: RequestBody): Promise<APIResponse<T>>;
     put<T = unknown>(url: string, body: RequestBody, config: RequestConfig): Promise<APIResponse<T>>;
     /**
-     * PATCH request method overloads
+     * @summary Performs PATCH requests to the API
+     * @description Makes HTTP PATCH requests to update parts of resources in the API
      */
     patch<T = unknown>(url: string): Promise<APIResponse<T>>;
     patch<T = unknown>(url: string, body: RequestBody): Promise<APIResponse<T>>;
     patch<T = unknown>(url: string, body: RequestBody, config: RequestConfig): Promise<APIResponse<T>>;
     /**
-     * DELETE request method overloads
+     * @summary Performs DELETE requests to the API
+     * @description Makes HTTP DELETE requests to remove resources from the API
      */
     delete<T = unknown>(url: string): Promise<APIResponse<T>>;
     delete<T = unknown>(url: string, config: RequestConfig): Promise<APIResponse<T>>;
     /**
-     * Core request method with comprehensive error handling and retry logic
+     * @category HTTP Client
+     * @summary Core request method with comprehensive error handling and retry logic
+     * @description Handles all HTTP requests with error handling, retries, and interceptors
      *
      * @param method - HTTP method to use
      * @param url - Request URL (relative to baseURL)
@@ -75,71 +104,141 @@ export declare class HttpClient {
      */
     private request;
     /**
-     * Makes the actual HTTP request with timeout handling
+     * @category HTTP Client Internals
+     * @summary Makes the actual HTTP request with timeout handling
+     * @description Performs the fetch request with timeout handling and abort controller
+     *
+     * @param url - Full URL to request
+     * @param options - Fetch request options
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to API response
      */
     private makeRequest;
     /**
-     * Processes the fetch response and converts to APIResponse format
+     * @category HTTP Client Internals
+     * @summary Processes the fetch response and converts to APIResponse format
+     * @description Parses the response and formats it according to the APIResponse interface
+     *
+     * @param response - The raw fetch Response object
+     * @returns Processed API response
      */
     private processResponse;
     /**
-     * Creates appropriate error based on response status and data
+     * @category HTTP Client Internals
+     * @summary Creates appropriate error based on response status and data
+     * @description Maps HTTP status codes to specific Tapsilat error types
+     *
+     * @param response - The raw fetch Response object
+     * @param data - The parsed response data
+     * @returns Appropriate TapsilatError subclass instance
      */
     private createErrorFromResponse;
     /**
-     * Extracts error message from response data
+     * @category HTTP Client Internals
+     * @summary Extracts error message from response data
+     * @description Attempts to find an error message in various locations within the response
+     *
+     * @param data - The parsed response data
+     * @returns Error message if found
      */
     private extractErrorMessage;
     /**
-     * Extracts validation details from error response
+     * @category HTTP Client Internals
+     * @summary Extracts validation details from error response
+     * @description Parses field-specific validation errors from the API response
+     *
+     * @param data - The parsed response data
+     * @returns Object mapping field names to error messages
      */
     private extractValidationDetails;
     /**
-     * Extracts rate limit information from response headers
+     * @category HTTP Client Internals
+     * @summary Extracts rate limit information from response headers
+     * @description Reads and parses rate limiting headers from the API response
+     *
+     * @param response - The raw fetch Response object
+     * @returns Rate limit information including limits and reset time
      */
     private extractRateLimitInfo;
     /**
-     * Builds the complete URL for the request
+     * @category HTTP Client Internals
+     * @summary Builds the complete URL for the request
+     * @description Constructs the full URL with base URL and query parameters
+     *
+     * @param url - The endpoint path or full URL
+     * @param customBaseURL - Optional override for the base URL
+     * @param params - Optional query parameters
+     * @returns Complete request URL
      */
     private buildUrl;
     /**
-     * Builds RequestInit options for the fetch request
+     * @category HTTP Client Internals
+     * @summary Builds RequestInit options for the fetch request
+     * @description Prepares headers and request configuration for fetch API
+     *
+     * @param method - The HTTP method to use
+     * @param body - Optional request body
+     * @param config - Additional request configuration
+     * @returns Configured RequestInit object for fetch
      */
     private buildRequestOptions;
     /**
-     * Determines if an error should prevent retrying
+     * @category HTTP Client Internals
+     * @summary Determines if an error should prevent retrying
+     * @description Checks error types to decide if retry attempts should be aborted
+     *
+     * @param error - The error that occurred
+     * @returns Whether retry should be prevented for this error
      */
     private shouldNotRetry;
     /**
-     * Calculates retry delay with exponential backoff
+     * @category HTTP Client Internals
+     * @summary Calculates retry delay with exponential backoff
+     * @description Implements exponential backoff with jitter for retry attempts
+     *
+     * @param attempt - The current retry attempt number (0-indexed)
+     * @returns Delay in milliseconds before next retry
      */
     private calculateRetryDelay;
     /**
-     * Utility method to create delay
+     * @category HTTP Client Internals
+     * @summary Utility method to create delay
+     * @description Creates a promise that resolves after the specified time
+     *
+     * @param ms - Delay time in milliseconds
+     * @returns Promise that resolves after the delay
      */
     private delay;
     /**
-     * Gets the interceptor manager for advanced request/response handling
+     * @category Interceptors
+     * @summary Gets the interceptor manager for advanced request/response handling
+     * @description Provides access to the internal interceptor manager for custom handling
      *
      * @returns InterceptorManager instance
      */
     getInterceptors(): InterceptorManager;
     /**
-     * Adds a request interceptor
+     * @category Interceptors
+     * @summary Adds a request interceptor
+     * @description Registers a function to intercept and modify requests before they are sent
      *
      * @param interceptor - Request interceptor function
      * @returns Interceptor ID for removal
      */
     addRequestInterceptor(interceptor: Parameters<InterceptorManager["addRequestInterceptor"]>[0]): number;
     /**
-     * Adds a response interceptor
+     * @category Interceptors
+     * @summary Adds a response interceptor
+     * @description Registers a function to intercept and modify responses before they are returned
      *
      * @param interceptor - Response interceptor function
      * @returns Interceptor ID for removal
      */
     addResponseInterceptor(interceptor: Parameters<InterceptorManager["addResponseInterceptor"]>[0]): number;
     /**
-     * Adds an error interceptor
+     * @category Interceptors
+     * @summary Adds an error interceptor
+     * @description Registers a function to intercept and potentially recover from errors
      *
      * @param interceptor - Error interceptor function
      * @returns Interceptor ID for removal

package/dist/http/HttpClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpClient.d.ts","sourceRoot":"","sources":["../../src/http/HttpClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HttpClient.d.ts","sourceRoot":"","sources":["../../src/http/HttpClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAQ7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,MAAM,CAAC;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACnB,MAAM,GACN,OAAO,EAAE,GACT,MAAM,GACN,QAAQ,CAAC;AAEb;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4B;IAEzD;;;;;OAKG;gBACS,MAAM,EAAE,cAAc;IAIlC;;;OAGG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACtD,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAQ1B;;;OAGG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACvD,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAS1B;;;OAGG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACtD,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACpB,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAS1B;;;OAGG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACxD,KAAK,CAAC,CAAC,GAAG,OAAO,EACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACpB,KAAK,CAAC,CAAC,GAAG,OAAO,EACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAS1B;;;OAGG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,CAAC,CAAC,GAAG,OAAO,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAQ1B;;;;;;;;;;OAUG;YACW,OAAO;IAgErB;;;;;;;;;OASG;YACW,WAAW;IA0CzB;;;;;;;OAOG;YACW,eAAe;IAuC7B;;;;;;;;OAQG;IACH,OAAO,CAAC,uBAAuB;IA6D/B;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAUhC;;;;;;;OAOG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ;IAoChB;;;;;;;;;OASG;YACW,mBAAmB;IAuCjC;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK;IAMb;;;;;;OAMG;IACH,eAAe,IAAI,kBAAkB;IAIrC;;;;;;;OAOG;IACH,qBAAqB,CACnB,WAAW,EAAE,UAAU,CAAC,kBAAkB,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,GACtE,MAAM;IAIT;;;;;;;OAOG;IACH,sBAAsB,CACpB,WAAW,EAAE,UAAU,CAAC,kBAAkB,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAC,CAAC,GACvE,MAAM;IAIT;;;;;;;OAOG;IACH,mBAAmB,CACjB,WAAW,EAAE,UAAU,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,GACpE,MAAM;CAGV"}

package/dist/http/interceptors.d.ts

@@ -1,4 +1,14 @@
-import { APIResponse } from "../types";
+/**
+ * @category HTTP
+ * @module Interceptors
+ */
+import { APIResponse } from "../types/index";
+/**
+ * @category Interceptors
+ * @summary Function type for modifying HTTP requests before they are sent
+ * @description Allows preprocessing of URL and request options before the API call is made
+ * @typedef {Function} RequestInterceptor
+ */
 export type RequestInterceptor = (url: string, options: RequestInit) => Promise<{
     url: string;
     options: RequestInit;
@@ -6,43 +16,149 @@ export type RequestInterceptor = (url: string, options: RequestInit) => Promise<
     url: string;
     options: RequestInit;
 };
+/**
+ * @category Interceptors
+ * @summary Function type for processing HTTP responses before returning to caller
+ * @description Allows transformation and analysis of API responses after receiving them but before they reach the calling code
+ * @typedef {Function} ResponseInterceptor
+ */
 export type ResponseInterceptor = (response: APIResponse<any>, request: {
     url: string;
     options: RequestInit;
 }) => Promise<APIResponse<any>> | APIResponse<any>;
+/**
+ * @category Interceptors
+ * @summary Function type for handling errors that occur during HTTP requests
+ * @description Provides opportunity to recover from errors, transform them, or perform logging operations before they propagate
+ * @typedef {Function} ErrorInterceptor
+ */
 export type ErrorInterceptor = (error: Error, request: {
     url: string;
     options: RequestInit;
 }) => Promise<never | APIResponse<any>> | never | APIResponse<any>;
+/**
+ * @category HTTP
+ * @summary Central registry and execution engine for all HTTP interceptors
+ * @description Maintains lists of request, response and error interceptors and provides methods to execute them in sequence
+ * @class InterceptorManager
+ */
 export declare class InterceptorManager {
     private requestInterceptors;
     private responseInterceptors;
     private errorInterceptors;
+    /**
+     * Adds a request interceptor to the chain
+     *
+     * @summary Register a new request interceptor function
+     * @description Adds a new interceptor to process requests before they are sent
+     *
+     * @param interceptor - The request interceptor function to add
+     * @returns The index of the added interceptor (can be used to remove it later)
+     */
     addRequestInterceptor(interceptor: RequestInterceptor): number;
+    /**
+     * Removes a previously added request interceptor
+     *
+     * @summary Unregister a request interceptor by its ID
+     * @description Removes the request interceptor at the specified position
+     *
+     * @param id - The index of the interceptor to remove
+     */
     removeRequestInterceptor(id: number): void;
+    /**
+     * Runs all registered request interceptors in sequence
+     *
+     * @summary Process a request through all interceptors
+     * @description Executes each registered request interceptor in order, passing modified url and options to each
+     *
+     * @param url - The initial request URL
+     * @param options - The initial request options
+     * @returns Modified URL and options after all interceptors have processed them
+     */
     executeRequestInterceptors(url: string, options: RequestInit): Promise<{
         url: string;
         options: RequestInit;
     }>;
+    /**
+     * @summary Register a new response interceptor function
+     * @description Adds a new interceptor to process responses before they are returned to the caller
+     *
+     * @param interceptor - The response interceptor function to add
+     * @returns The index of the added interceptor (can be used to remove it later)
+     */
     addResponseInterceptor(interceptor: ResponseInterceptor): number;
+    /**
+     * @summary Unregister a response interceptor by its ID
+     * @description Removes the response interceptor at the specified position
+     *
+     * @param id - The index of the interceptor to remove
+     */
     removeResponseInterceptor(id: number): void;
+    /**
+     * @summary Process a response through all interceptors
+     * @description Executes each registered response interceptor in order
+     *
+     * @param response - The API response to process
+     * @param request - The original request information
+     * @returns Modified response after all interceptors have processed it
+     */
     executeResponseInterceptors<T>(response: APIResponse<T>, request: {
         url: string;
         options: RequestInit;
     }): Promise<APIResponse<T>>;
+    /**
+     * @summary Register a new error interceptor function
+     * @description Adds a new interceptor to process errors before they are thrown
+     *
+     * @param interceptor - The error interceptor function to add
+     * @returns The index of the added interceptor (can be used to remove it later)
+     */
     addErrorInterceptor(interceptor: ErrorInterceptor): number;
+    /**
+     * @summary Unregister an error interceptor by its ID
+     * @description Removes the error interceptor at the specified position
+     *
+     * @param id - The index of the interceptor to remove
+     */
     removeErrorInterceptor(id: number): void;
+    /**
+     * @summary Process an error through all interceptors
+     * @description Executes each registered error interceptor in order until one handles the error
+     *
+     * @param error - The error that occurred during the request
+     * @param request - The original request information
+     * @returns Either a recovery response or throws the error if no interceptors handle it
+     */
     executeErrorInterceptors(error: Error, request: {
         url: string;
         options: RequestInit;
     }): Promise<never | APIResponse<any>>;
+    /**
+     * @summary Remove all registered interceptors
+     * @description Clears all request, response, and error interceptors at once
+     */
     clear(): void;
 }
+/**
+ * @category Built-in Interceptors
+ * @summary Creates a set of interceptors for logging API requests, responses, and errors
+ * @description Provides detailed logging of HTTP activity when debug mode is enabled
+ *
+ * @param debug - When true, enables console logging of API activities
+ * @returns Object containing request, response, and error interceptors for logging
+ */
 export declare const createLoggingInterceptor: (debug?: boolean) => {
     request: RequestInterceptor;
     response: ResponseInterceptor;
     error: ErrorInterceptor;
 };
+/**
+ * @category Built-in Interceptors
+ * @summary Creates interceptors for measuring API request/response times
+ * @description Tracks the duration of API calls and logs performance metrics
+ *
+ * @returns Object containing request and response interceptors for timing measurement
+ */
 export declare const createTimingInterceptor: () => {
     request: RequestInterceptor;
     response: ResponseInterceptor;

package/dist/http/interceptors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../../src/http/interceptors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,KAElB,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC,GAC9C;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAE1C,MAAM,MAAM,mBAAmB,GAAG,CAChC,QAAQ,EAAE,WAAW,CAAC,GAAG,CAAC,EAC1B,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,KAC3C,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,KAC3C,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAElE,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,iBAAiB,CAA0B;IAGnD,qBAAqB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM;IAK9D,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMpC,0BAA0B,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC;IAgBjD,sBAAsB,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM;IAKhE,yBAAyB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMrC,2BAA2B,CAAC,CAAC,EACjC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,EACxB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,GAC7C,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAa1B,mBAAmB,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM;IAK1D,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMlC,wBAAwB,CAC5B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,GAC7C,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAiBpC,KAAK,IAAI,IAAI;CAKd;AAGD,eAAO,MAAM,wBAAwB,GACnC,QAAO,OAAe,KACrB;IACD,OAAO,EAAE,kBAAkB,CAAC;IAC5B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,EAAE,gBAAgB,CAAC;CA+BxB,CAAC;AAEH,eAAO,MAAM,uBAAuB,QAAO;IACzC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,QAAQ,EAAE,mBAAmB,CAAC;CAkC/B,CAAC"}
+{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../../src/http/interceptors.ts"],"names":[],"mappings":"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"}