@hashrytech/quick-components-kit 0.11.1 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @hashrytech/quick-components-kit
 
+## 0.12.1
+
+### Patch Changes
+
+- refactor: Using a typed wrapper approach for API Client
+
+## 0.12.0
+
+### Minor Changes
+
+- feat: Adding api-client, api-proxy, crypto and problem-details modules
+
 ## 0.11.1
 
 ### Patch Changes

package/dist/{checkbox → components/checkbox}/Checkbox.svelte.d.ts

@@ -15,6 +15,6 @@ export type CheckBoxProps = {
     labelClass?: ClassNameValue;
     class?: ClassNameValue;
 };
-declare const Checkbox: import("svelte").Component<CheckBoxProps, {}, "disabled" | "checked" | "group">;
+declare const Checkbox: import("svelte").Component<CheckBoxProps, {}, "disabled" | "group" | "checked">;
 type Checkbox = ReturnType<typeof Checkbox>;
 export default Checkbox;

package/dist/{drawer → components/drawer}/Drawer.svelte

@@ -4,7 +4,7 @@
     import { fly } from 'svelte/transition';
     import {twMerge} from 'tailwind-merge';
     import Overlay from '../overlay/Overlay.svelte';
-    import { onKeydown } from '../actions/on-keydown.js';
+    import { onKeydown } from '../../actions/on-keydown.js';
     
     export type DrawerProps = {
       open?: boolean;

package/dist/{modal → components/modal}/Modal.svelte

@@ -4,8 +4,8 @@
     import { fade } from 'svelte/transition';
     import {twMerge} from 'tailwind-merge';
 	  import { browser } from '$app/environment';
-	import Overlay from '../overlay/Overlay.svelte';
-	import { onKeydown } from '../actions/on-keydown.js';
+	  import Overlay from '../overlay/Overlay.svelte';
+	  import { onKeydown } from '../../actions/on-keydown.js';
     
     export type ModalProps = {
       open?: boolean;

package/dist/{overlay → components/overlay}/Overlay.svelte

@@ -1,9 +1,9 @@
 <script lang="ts" module>    
-	  import { onDestroy, onMount, type Snippet } from 'svelte';
+	  import { type Snippet } from 'svelte';
     import type { ClassNameValue } from 'tailwind-merge';
     import { fade } from 'svelte/transition';
     import {twMerge} from 'tailwind-merge';
-    import { disableScroll } from '../actions/disable-scroll.js';
+    import { disableScroll } from '../../actions/disable-scroll.js';
     
     export type OverlayProps = {
       disableBodyScroll?: boolean;

package/dist/index.d.ts

@@ -1,11 +1,17 @@
-export * from './text-input/index.js';
-export * from './button/index.js';
-export * from './link-button/index.js';
-export * from './hamburger-menu/index.js';
-export * from './drawer/index.js';
-export * from './modal/index.js';
-export * from './overlay/index.js';
+export * from './components/text-input/index.js';
+export * from './components/button/index.js';
+export * from './components/link-button/index.js';
+export * from './components/hamburger-menu/index.js';
+export * from './components/drawer/index.js';
+export * from './components/modal/index.js';
+export * from './components/overlay/index.js';
+export * from './components/radio/index.js';
+export * from './components/checkbox/index.js';
 export * from './actions/disable-scroll.js';
 export * from './actions/on-keydown.js';
 export * from './actions/lock-scroll.js';
 export * from './actions/scroll-to.js';
+export * from './modules/api-client.js';
+export * from './modules/api-proxy.js';
+export * from './modules/crypto.js';
+export * from './modules/problem-details.js';

package/dist/index.js

@@ -1,14 +1,20 @@
 // Reexport your entry components here
 // lib/index.js
-export * from './text-input/index.js';
-export * from './button/index.js';
-export * from './link-button/index.js';
-export * from './hamburger-menu/index.js';
-export * from './drawer/index.js';
-export * from './modal/index.js';
-export * from './overlay/index.js';
+export * from './components/text-input/index.js';
+export * from './components/button/index.js';
+export * from './components/link-button/index.js';
+export * from './components/hamburger-menu/index.js';
+export * from './components/drawer/index.js';
+export * from './components/modal/index.js';
+export * from './components/overlay/index.js';
+export * from './components/radio/index.js';
+export * from './components/checkbox/index.js';
 export * from './actions/disable-scroll.js';
 export * from './actions/on-keydown.js';
 export * from './actions/lock-scroll.js';
 export * from './actions/scroll-to.js';
+export * from './modules/api-client.js';
+export * from './modules/api-proxy.js';
+export * from './modules/crypto.js';
+export * from './modules/problem-details.js';
 // Add more components here...

package/dist/modules/api-client.d.ts

@@ -0,0 +1,253 @@
+/**
+ * @file This module defines a generic REST API client for SvelteKit applications.
+ * It provides methods for standard HTTP operations (GET, POST, PUT, PATCH, DELETE),
+ * supports authentication via Bearer tokens, includes customizable middleware hooks
+ * for request and response processing, and handles file uploads and downloads.
+ *
+ * It's designed to be used with SvelteKit's `fetch` (which is global in load functions
+ * and API routes) to automatically benefit from its enhancements (e.g., cookie forwarding,
+ * built-in request/response interception via SvelteKit's `handleFetch` hook).
+ */
+export type ApiResponse<T> = {
+    ok: boolean;
+    status: number;
+    data?: T;
+    error?: string;
+};
+export interface ApiClientConfig {
+    /** The base URL for your API (e.g., 'https://api.yourapi.com/v1'). */
+    baseURL: string;
+    /** Default headers to be sent with every request. */
+    defaultHeaders?: HeadersInit;
+    /** A function that returns the current access token. This is useful for client-side
+     * operations where you might store the token in a Svelte store or similar.
+     * For server-side operations using SvelteKit's `fetch`, the token is typically
+     * handled by `src/hooks.server.ts` via `handleFetch`.
+     */
+    getAccessToken?: () => string | undefined;
+}
+export interface RequestOptions extends RequestInit {
+    /** If true, the Authorization header will not be added to this request. */
+    skipAuth?: boolean;
+    /** Specifies how the response body should be parsed.
+     * 'json' (default): Parses as JSON.
+     * 'text': Parses as plain text.
+     * 'blob': Parses as a Blob (useful for file downloads).
+     * 'arrayBuffer': Parses as an ArrayBuffer.
+     * 'raw': Returns the raw Response object without parsing the body.
+     */
+    responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'raw';
+    /**
+     * The `fetch` function to use for making the request.
+     * In SvelteKit:
+     * - In `+page.server.ts`, `+layout.server.ts`, `+server.ts` it's the enhanced `fetch` passed to `load` functions/handlers.
+     * - In `+page.svelte`, `+layout.svelte`, `+client.ts` it's the browser's global `fetch`.
+     */
+    fetchInstance?: typeof fetch;
+}
+export type RequestInterceptor = (request: Request) => Promise<Request> | Request;
+export type ResponseInterceptor = (response: Response) => Promise<Response> | Response;
+export type ErrorHandler = (error: Error) => Promise<void> | void;
+/**
+ * Custom error class for API responses.
+ * Provides access to the HTTP status code.
+ */
+export declare class ApiError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+export interface ApiClientEvents {
+    onRequest?: (request: Request) => void;
+    onResponse?: (response: Response) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * A generic REST API client.
+ *
+ * Features:
+ * - Configurable base URL and default headers.
+ * - Supports GET, POST, PUT, PATCH, DELETE methods.
+ * - Handles Bearer token authentication.
+ * - Customizable request and response interceptors (middleware hooks).
+ * - Centralized error handling.
+ * - Supports file uploads (FormData).
+ * - Supports file downloads (returns Blob).
+ * - Integrates with SvelteKit's `fetch` for server-side benefits.
+ */
+export declare class ApiClient {
+    private baseURL;
+    private defaultHeaders;
+    private clientAuthToken;
+    private getAccessTokenFromStore;
+    private requestInterceptors;
+    private responseInterceptors;
+    private errorHandlers;
+    private events;
+    /**
+     * Creates an instance of ApiClient.
+     * @param config - Configuration for the API client.
+     */
+    constructor(config: ApiClientConfig & {
+        events?: ApiClientEvents;
+    });
+    /**
+     * Sets the Bearer token for client-side requests.
+     * This will override `getAccessToken` for subsequent requests using this client instance.
+     * @param token - The access token string, or undefined to clear it.
+     */
+    setAuthToken(token: string | undefined): void;
+    /**
+     * Adds a request interceptor. Interceptors can modify the `Request` object before it's sent.
+     * @param interceptor - A function that takes a `Request` object and returns a `Request` or a Promise resolving to a `Request`.
+     */
+    addRequestInterceptor(interceptor: RequestInterceptor): void;
+    /**
+     * Adds a response interceptor. Interceptors can modify the `Response` object after it's received but before parsing.
+     * Useful for global error handling (e.g., refreshing tokens on 401).
+     * @param interceptor - A function that takes a `Response` object and returns a `Response` or a Promise resolving to a `Response`.
+     */
+    addResponseInterceptor(interceptor: ResponseInterceptor): void;
+    /**
+     * Adds a global error handler. These handlers are called when a request fails (network error or non-2xx API response).
+     * @param handler - A function that takes an `Error` object.
+     */
+    addErrorHandler(handler: ErrorHandler): void;
+    setEventHooks(events: Partial<ApiClientEvents>): void;
+    /**
+     * Processes the request, applying default headers, auth token, and request interceptors.
+     * @param endpoint - The API endpoint (e.g., '/products', '/users/123').
+     * @param method - HTTP method (GET, POST, etc.).
+     * @param body - The request body.
+     * @param options - Additional request options.
+     * @returns A processed `Request` object ready for `fetch`.
+     */
+    private processRequest;
+    /**
+     * Processes the response, applying response interceptors and parsing the body.
+     * @param response - The raw `Response` object from `fetch`.
+     * @param options - The request options, used for `responseType`.
+     * @returns The parsed response data or the raw `Response` object.
+     * @throws `ApiError` if the response status is not OK (2xx).
+     */
+    private processResponse;
+    /**
+     * Handles errors by invoking registered error handlers.
+     * @param error - The error that occurred during the request (type unknown to handle all potential errors).
+     * @throws The original error if no handler fully resolves it.
+     */
+    private handleError;
+    /**
+     * Generic request method. All other HTTP methods call this.
+     * @param endpoint - The API endpoint.
+     * @param method - The HTTP method.
+     * @param body - The request body (optional). Can be BodyInit (string, Blob, FormData etc.) or a plain object (which will be JSON.stringified).
+     * @param options - Request options.
+     * @returns A Promise resolving to the parsed response data or raw Response/Blob.
+     * @template T - Expected type of the response data.
+     */
+    request<T>(endpoint: string, method: string, body: BodyInit | object | null | undefined, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Sends a GET request to the specified API endpoint.
+     *
+     * @param endpoint - The relative path (e.g., `/users` or `/orders/123`).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response.
+     */
+    get<T>(endpoint: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Sends a POST request to the specified API endpoint.
+     *
+     * @param endpoint - The relative path (e.g., `/products`).
+     * @param data - The request body (object, JSON, or FormData).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response.
+     */
+    post<T>(endpoint: string, data?: BodyInit | object | null, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Sends a PUT request to the specified API endpoint.
+     * Typically used for full resource replacement.
+     *
+     * @param endpoint - The relative path (e.g., `/products/123`).
+     * @param data - The request body (object, JSON, or FormData).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response.
+     */
+    put<T>(endpoint: string, data?: BodyInit | object | null, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Sends a PATCH request to the specified API endpoint.
+     * Typically used for partial updates.
+     *
+     * @param endpoint - The relative path (e.g., `/users/123`).
+     * @param data - The partial resource update (object or FormData).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response.
+     */
+    patch<T>(endpoint: string, data?: BodyInit | object | null, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Sends a DELETE request to the specified API endpoint.
+     *
+     * @param endpoint - The relative path (e.g., `/orders/456`).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response (if any).
+     */
+    delete<T>(endpoint: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Handles file uploads.
+     * @param endpoint - The API endpoint for file upload.
+     * @param file - The file to upload (File, Blob, or FormData). If Blob/File, it's wrapped in FormData.
+     * @param fieldName - The name of the form field for the file (default: 'file').
+     * @param options - Additional request options.
+     * @returns A Promise resolving to the parsed response data.
+     * @template T - Expected type of the response data after upload.
+     */
+    uploadFile<T>(endpoint: string, file: File | Blob | FormData, fieldName?: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Handles file downloads.
+     * @param endpoint - The API endpoint for file download.
+     * @param options - Additional request options.
+     * @returns A Promise resolving to a `Blob` containing the file data.
+     */
+    downloadFile(endpoint: string, options?: RequestOptions): Promise<Blob>;
+    /**
+     * Uploads a file to the specified API endpoint using XMLHttpRequest to track upload progress.
+     *
+     * This method supports file uploads via `multipart/form-data`, reports progress using a callback,
+     * and handles authentication headers and additional request headers.
+     *
+     * @param endpoint - The API endpoint to upload the file to (relative to baseURL).
+     * @param file - The file or blob to upload.
+     * @param onProgress - A callback that receives percentage progress updates (0–100).
+     * @param fieldName - The name of the form field used for the file (default is 'file').
+     * @param options - Optional request settings (headers, skipAuth, etc.).
+     * @returns A Promise resolving to the typed response from the server.
+     * @template T - Expected shape of the server's JSON response.
+     */
+    uploadFileWithProgress<T>(endpoint: string, file: File | Blob, onProgress: (percent: number) => void, fieldName?: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Downloads a file from the specified endpoint while reporting progress.
+     *
+     * This method streams the response using a readable stream, reads it chunk by chunk,
+     * and accumulates the data into a Blob. During the download, it calculates and emits
+     * percentage progress updates if the `Content-Length` header is provided.
+     *
+     * @param endpoint - The API endpoint to download the file from.
+     * @param onProgress - Callback that receives progress updates (as a percent from 0 to 100).
+     * @param options - Optional request options including headers, credentials, etc.
+     * @returns A Promise that resolves to a Blob containing the downloaded file.
+     */
+    downloadWithProgress(endpoint: string, onProgress: (percent: number) => void, options?: RequestOptions): Promise<Blob>;
+    /**
+     * Executes multiple request functions concurrently and infers their return types.
+     *
+     * @param requests - An array of functions that each return a typed Promise.
+     * @returns A Promise resolving to an array of results, with types preserved.
+     */
+    batch<T extends ReadonlyArray<() => Promise<unknown>>>(requests: T): Promise<{
+        [K in keyof T]: T[K] extends () => Promise<infer R> ? R : never;
+    }>;
+}

package/dist/modules/api-client.js

@@ -0,0 +1,464 @@
+// src/lib/api/client.ts
+/**
+ * Custom error class for API responses.
+ * Provides access to the HTTP status code.
+ */
+export class ApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+    }
+}
+/**
+ * A generic REST API client.
+ *
+ * Features:
+ * - Configurable base URL and default headers.
+ * - Supports GET, POST, PUT, PATCH, DELETE methods.
+ * - Handles Bearer token authentication.
+ * - Customizable request and response interceptors (middleware hooks).
+ * - Centralized error handling.
+ * - Supports file uploads (FormData).
+ * - Supports file downloads (returns Blob).
+ * - Integrates with SvelteKit's `fetch` for server-side benefits.
+ */
+export class ApiClient {
+    baseURL;
+    defaultHeaders;
+    // This token is primarily for explicit client-side setting if needed,
+    // otherwise relies on getAccessTokenFromStore or SvelteKit's `handleFetch`.
+    clientAuthToken;
+    getAccessTokenFromStore;
+    requestInterceptors = [];
+    responseInterceptors = [];
+    errorHandlers = [];
+    events = {};
+    /**
+     * Creates an instance of ApiClient.
+     * @param config - Configuration for the API client.
+     */
+    constructor(config) {
+        this.baseURL = config.baseURL;
+        this.defaultHeaders = config.defaultHeaders || { 'Content-Type': 'application/json' };
+        this.getAccessTokenFromStore = config.getAccessToken;
+    }
+    /**
+     * Sets the Bearer token for client-side requests.
+     * This will override `getAccessToken` for subsequent requests using this client instance.
+     * @param token - The access token string, or undefined to clear it.
+     */
+    setAuthToken(token) {
+        this.clientAuthToken = token;
+    }
+    /**
+     * Adds a request interceptor. Interceptors can modify the `Request` object before it's sent.
+     * @param interceptor - A function that takes a `Request` object and returns a `Request` or a Promise resolving to a `Request`.
+     */
+    addRequestInterceptor(interceptor) {
+        this.requestInterceptors.push(interceptor);
+    }
+    /**
+     * Adds a response interceptor. Interceptors can modify the `Response` object after it's received but before parsing.
+     * Useful for global error handling (e.g., refreshing tokens on 401).
+     * @param interceptor - A function that takes a `Response` object and returns a `Response` or a Promise resolving to a `Response`.
+     */
+    addResponseInterceptor(interceptor) {
+        this.responseInterceptors.push(interceptor);
+    }
+    /**
+     * Adds a global error handler. These handlers are called when a request fails (network error or non-2xx API response).
+     * @param handler - A function that takes an `Error` object.
+     */
+    addErrorHandler(handler) {
+        this.errorHandlers.push(handler);
+    }
+    setEventHooks(events) {
+        Object.assign(this.events, events);
+    }
+    /**
+     * Processes the request, applying default headers, auth token, and request interceptors.
+     * @param endpoint - The API endpoint (e.g., '/products', '/users/123').
+     * @param method - HTTP method (GET, POST, etc.).
+     * @param body - The request body.
+     * @param options - Additional request options.
+     * @returns A processed `Request` object ready for `fetch`.
+     */
+    async processRequest(endpoint, method, body, options) {
+        const url = new URL(endpoint, this.baseURL); // Resolve endpoint relative to baseURL
+        const requestHeaders = new Headers(this.defaultHeaders);
+        // Merge custom headers from options using Headers constructor for robustness
+        if (options.headers) {
+            // Create a temporary Headers object from options.headers to iterate consistently
+            const incomingHeaders = new Headers(options.headers);
+            for (const [key, value] of incomingHeaders.entries()) {
+                requestHeaders.set(key, value);
+            }
+        }
+        // Add auth token unless skipped
+        if (!options.skipAuth) {
+            // Priority: Explicit clientAuthToken > getAccessTokenFromStore
+            const token = this.clientAuthToken || (this.getAccessTokenFromStore ? this.getAccessTokenFromStore() : undefined);
+            if (token) {
+                requestHeaders.set('Authorization', `Bearer ${token}`);
+            }
+        }
+        let processedBody = undefined;
+        if (body instanceof FormData) {
+            requestHeaders.delete('Content-Type'); // Important: Let browser set Content-Type for FormData
+            processedBody = body;
+        }
+        else if (body !== undefined && body !== null) {
+            const contentType = requestHeaders.get('Content-Type');
+            // If Content-Type is JSON or it's a plain object (and not a Blob/File/Stream type of BodyInit), stringify it.
+            if (contentType?.includes('application/json') ||
+                (typeof body === 'object' &&
+                    !(body instanceof Blob) &&
+                    !(body instanceof ArrayBuffer) &&
+                    !(body instanceof ReadableStream) && // Covers streams like Node.js Buffer
+                    !(body instanceof URLSearchParams))) {
+                processedBody = JSON.stringify(body);
+            }
+            else {
+                // Otherwise, assume `body` is already a valid BodyInit (string, Blob, ArrayBuffer, etc.)
+                // A direct cast is used here as the prior checks narrow the type.
+                processedBody = body;
+            }
+        }
+        let request = new Request(url.toString(), {
+            method: method,
+            headers: requestHeaders,
+            body: processedBody,
+            ...options // Spread other fetch options like cache, credentials etc.
+        });
+        // Apply request interceptors sequentially
+        for (const interceptor of this.requestInterceptors) {
+            request = await Promise.resolve(interceptor(request));
+        }
+        return request;
+    }
+    /**
+     * Processes the response, applying response interceptors and parsing the body.
+     * @param response - The raw `Response` object from `fetch`.
+     * @param options - The request options, used for `responseType`.
+     * @returns The parsed response data or the raw `Response` object.
+     * @throws `ApiError` if the response status is not OK (2xx).
+     */
+    async processResponse(response, options) {
+        // Apply response interceptors sequentially
+        for (const interceptor of this.responseInterceptors) {
+            response = await Promise.resolve(interceptor(response));
+        }
+        if (!response.ok) {
+            let errorMessage = response.statusText;
+            let errorJson;
+            // Clone the response before reading body for error parsing,
+            // so original response body is still available if responseType is 'raw'.
+            const errorResponseClone = response.clone();
+            try {
+                // Attempt to parse a more descriptive error message from JSON response
+                errorJson = await errorResponseClone.json();
+                errorMessage = errorJson.message || errorJson.error || JSON.stringify(errorJson);
+            }
+            catch (e) {
+                // If response is not JSON, use default status text or log parsing error
+                console.warn('API Client: Failed to parse error response as JSON.', e);
+            }
+            throw new ApiError(errorMessage, response.status);
+        }
+        switch (options.responseType) {
+            case 'text':
+                return (await response.text());
+            case 'blob':
+                return (await response.blob());
+            case 'arrayBuffer':
+                return (await response.arrayBuffer());
+            case 'raw': return response;
+            case 'json':
+            default:
+                // Handle 204 No Content (or other non-body responses)
+                if (response.status === 204 || response.headers.get('Content-Length') === '0') {
+                    return {}; // Return an empty object for no content
+                }
+                try {
+                    return (await response.json());
+                }
+                catch {
+                    throw new Error('Failed to parse response as JSON. Response was OK, but not valid JSON.');
+                }
+        }
+    }
+    /**
+     * Handles errors by invoking registered error handlers.
+     * @param error - The error that occurred during the request (type unknown to handle all potential errors).
+     * @throws The original error if no handler fully resolves it.
+     */
+    async handleError(error) {
+        // Log the error by default
+        console.error("API Client encountered an error:", error);
+        // Cast to Error for common properties, or handle specifically
+        const err = error instanceof Error ? error : new Error(String(error));
+        // Apply registered error handlers
+        for (const handler of this.errorHandlers) {
+            await Promise.resolve(handler(err)); // Pass the Error object
+        }
+        // Re-throw the error if it hasn't been "handled" by a handler (e.g., by redirecting)
+        // This ensures the calling context can still catch and react to the error.
+        throw err;
+    }
+    /**
+     * Generic request method. All other HTTP methods call this.
+     * @param endpoint - The API endpoint.
+     * @param method - The HTTP method.
+     * @param body - The request body (optional). Can be BodyInit (string, Blob, FormData etc.) or a plain object (which will be JSON.stringified).
+     * @param options - Request options.
+     * @returns A Promise resolving to the parsed response data or raw Response/Blob.
+     * @template T - Expected type of the response data.
+     */
+    async request(endpoint, method, body, options = {}) {
+        const currentFetch = options.fetchInstance || fetch;
+        try {
+            const request = await this.processRequest(endpoint, method, body, options);
+            const response = await currentFetch(request);
+            const parsed = await this.processResponse(response, options);
+            return {
+                ok: true,
+                status: response.status,
+                data: parsed
+            };
+        }
+        catch (error) {
+            await this.handleError(error);
+            const status = error instanceof ApiError ? error.status : 500;
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                ok: false,
+                status,
+                error: message
+            };
+        }
+    }
+    // --- HTTP Method Shorthands ---
+    /**
+     * Sends a GET request to the specified API endpoint.
+     *
+     * @param endpoint - The relative path (e.g., `/users` or `/orders/123`).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response.
+     */
+    get(endpoint, options) {
+        return this.request(endpoint, 'GET', undefined, options);
+    }
+    /**
+     * Sends a POST request to the specified API endpoint.
+     *
+     * @param endpoint - The relative path (e.g., `/products`).
+     * @param data - The request body (object, JSON, or FormData).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response.
+     */
+    post(endpoint, data, options) {
+        return this.request(endpoint, 'POST', data, options);
+    }
+    /**
+     * Sends a PUT request to the specified API endpoint.
+     * Typically used for full resource replacement.
+     *
+     * @param endpoint - The relative path (e.g., `/products/123`).
+     * @param data - The request body (object, JSON, or FormData).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response.
+     */
+    put(endpoint, data, options) {
+        return this.request(endpoint, 'PUT', data, options);
+    }
+    /**
+     * Sends a PATCH request to the specified API endpoint.
+     * Typically used for partial updates.
+     *
+     * @param endpoint - The relative path (e.g., `/users/123`).
+     * @param data - The partial resource update (object or FormData).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response.
+     */
+    patch(endpoint, data, options) {
+        return this.request(endpoint, 'PATCH', data, options);
+    }
+    /**
+     * Sends a DELETE request to the specified API endpoint.
+     *
+     * @param endpoint - The relative path (e.g., `/orders/456`).
+     * @param options - Optional request configuration.
+     * @returns A Promise resolving to the parsed response or raw Response object.
+     * @template T - Expected shape of the JSON response (if any).
+     */
+    delete(endpoint, options) {
+        // 'delete' is a reserved keyword, but acceptable as a method name in classes.
+        // If you encounter issues with specific environments, you could rename to 'del' or 'remove'.
+        return this.request(endpoint, 'DELETE', undefined, options);
+    }
+    // --- File Operations ---
+    /**
+     * Handles file uploads.
+     * @param endpoint - The API endpoint for file upload.
+     * @param file - The file to upload (File, Blob, or FormData). If Blob/File, it's wrapped in FormData.
+     * @param fieldName - The name of the form field for the file (default: 'file').
+     * @param options - Additional request options.
+     * @returns A Promise resolving to the parsed response data.
+     * @template T - Expected type of the response data after upload.
+     */
+    uploadFile(endpoint, file, fieldName = 'file', options) {
+        let uploadBody;
+        if (file instanceof File || file instanceof Blob) {
+            uploadBody = new FormData();
+            uploadBody.append(fieldName, file);
+        }
+        else if (file instanceof FormData) {
+            uploadBody = file;
+        }
+        else {
+            throw new Error('uploadFile expects a File, Blob, or FormData object.');
+        }
+        // Create new Headers based on provided options, and then delete 'Content-Type'.
+        // This ensures the browser sets the correct 'multipart/form-data' boundary.
+        const headers = new Headers(options?.headers);
+        headers.delete('Content-Type');
+        return this.request(endpoint, 'POST', uploadBody, { ...options, headers: headers });
+    }
+    /**
+     * Handles file downloads.
+     * @param endpoint - The API endpoint for file download.
+     * @param options - Additional request options.
+     * @returns A Promise resolving to a `Blob` containing the file data.
+     */
+    async downloadFile(endpoint, options) {
+        const response = await this.request(endpoint, 'GET', undefined, { ...options, responseType: 'blob' });
+        // Ensure the returned type is indeed a Blob before casting, for stricter type safety.
+        if (!(response instanceof Blob)) {
+            throw new Error('Expected Blob response for downloadFile, but got a different type or raw Response. Ensure responseType is explicitly set to "blob".');
+        }
+        return response;
+    }
+    /**
+     * Uploads a file to the specified API endpoint using XMLHttpRequest to track upload progress.
+     *
+     * This method supports file uploads via `multipart/form-data`, reports progress using a callback,
+     * and handles authentication headers and additional request headers.
+     *
+     * @param endpoint - The API endpoint to upload the file to (relative to baseURL).
+     * @param file - The file or blob to upload.
+     * @param onProgress - A callback that receives percentage progress updates (0–100).
+     * @param fieldName - The name of the form field used for the file (default is 'file').
+     * @param options - Optional request settings (headers, skipAuth, etc.).
+     * @returns A Promise resolving to the typed response from the server.
+     * @template T - Expected shape of the server's JSON response.
+     */
+    async uploadFileWithProgress(endpoint, file, onProgress, fieldName = 'file', options = {}) {
+        const url = new URL(endpoint, this.baseURL).toString();
+        const formData = new FormData();
+        formData.append(fieldName, file);
+        const token = this.clientAuthToken || this.getAccessTokenFromStore?.();
+        const headers = new Headers(this.defaultHeaders);
+        // Merge user-supplied headers
+        if (options.headers) {
+            const userHeaders = new Headers(options.headers);
+            userHeaders.forEach((value, key) => headers.set(key, value));
+        }
+        return new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open('POST', url, true);
+            // Add Authorization if not skipped
+            if (!options.skipAuth && token) {
+                xhr.setRequestHeader('Authorization', `Bearer ${token}`);
+            }
+            // Add any remaining headers
+            headers.forEach((value, key) => {
+                // Let the browser set Content-Type for FormData
+                if (key.toLowerCase() !== 'content-type') {
+                    xhr.setRequestHeader(key, value);
+                }
+            });
+            xhr.upload.onprogress = (event) => {
+                if (event.lengthComputable) {
+                    onProgress(Math.round((event.loaded / event.total) * 100));
+                }
+            };
+            xhr.onload = () => {
+                if (xhr.status >= 200 && xhr.status < 300) {
+                    const contentType = xhr.getResponseHeader('Content-Type') || '';
+                    if (contentType.includes('application/json')) {
+                        try {
+                            const json = JSON.parse(xhr.responseText);
+                            resolve(json);
+                        }
+                        catch {
+                            reject(new Error('Failed to parse JSON response'));
+                        }
+                    }
+                    else {
+                        // If not JSON, cast explicitly to unknown first, then to T
+                        resolve(xhr.responseText);
+                    }
+                }
+                else {
+                    reject(new ApiError(xhr.statusText, xhr.status));
+                }
+            };
+            xhr.onerror = () => reject(new Error('Upload failed'));
+            xhr.send(formData);
+        });
+    }
+    /**
+     * Downloads a file from the specified endpoint while reporting progress.
+     *
+     * This method streams the response using a readable stream, reads it chunk by chunk,
+     * and accumulates the data into a Blob. During the download, it calculates and emits
+     * percentage progress updates if the `Content-Length` header is provided.
+     *
+     * @param endpoint - The API endpoint to download the file from.
+     * @param onProgress - Callback that receives progress updates (as a percent from 0 to 100).
+     * @param options - Optional request options including headers, credentials, etc.
+     * @returns A Promise that resolves to a Blob containing the downloaded file.
+     */
+    async downloadWithProgress(endpoint, onProgress, options) {
+        const res = await this.request(endpoint, 'GET', undefined, { ...options, responseType: 'raw' });
+        if (!res.ok || !res.data) {
+            throw new Error(`Download failed: ${res.error ?? 'Unknown error'}`);
+        }
+        const response = res.data; // This is the raw Response object
+        const contentLengthHeader = response.headers.get('Content-Length');
+        const contentLength = contentLengthHeader ? parseInt(contentLengthHeader, 10) : 0;
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new Error('Failed to get reader from response body.');
+        const chunks = [];
+        let loaded = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                chunks.push(value);
+                loaded += value.length;
+                if (contentLength) {
+                    onProgress(Math.round((loaded / contentLength) * 100));
+                }
+            }
+        }
+        return new Blob(chunks);
+    }
+    /**
+     * Executes multiple request functions concurrently and infers their return types.
+     *
+     * @param requests - An array of functions that each return a typed Promise.
+     * @returns A Promise resolving to an array of results, with types preserved.
+     */
+    batch(requests) {
+        return Promise.all(requests.map((req) => req()));
+    }
+}

package/dist/modules/api-proxy.d.ts

@@ -0,0 +1,20 @@
+import type { RequestHandler } from '@sveltejs/kit';
+/**
+ * Configuration interface for the reusable proxy module.
+ */
+export interface ApiProxyConfig {
+    /** Your API base URL (e.g. 'https://api.example.com/v1') */
+    baseURL: string;
+    /** Allowed path prefixes for security */
+    allowedPaths: string[];
+    /** Optional extra headers to forward */
+    extraRequestHeaders?: string[];
+    /** Optional extra headers to return */
+    extraResponseHeaders?: string[];
+    /** Optional function to extract token from session */
+    extractToken?: (locals: App.Locals) => string | undefined;
+}
+/**
+ * Creates a set of SvelteKit request handlers for proxying API calls securely.
+ */
+export declare function createApiProxyHandlers(config: ApiProxyConfig): Record<string, RequestHandler>;

package/dist/modules/api-proxy.js

@@ -0,0 +1,58 @@
+import { error } from '@sveltejs/kit';
+/**
+ * Creates a set of SvelteKit request handlers for proxying API calls securely.
+ */
+export function createApiProxyHandlers(config) {
+    const safeRequestHeaders = [
+        'authorization', 'content-type', 'accept', 'accept-language',
+        'cookie', 'x-csrftoken', 'referer', 'user-agent', 'x-requested-with',
+        ...(config.extraRequestHeaders ?? [])
+    ];
+    const safeResponseHeaders = [
+        'content-type', 'content-length', 'cache-control', 'etag',
+        ...(config.extraResponseHeaders ?? [])
+    ];
+    async function handler(event) {
+        const path = event.params.path;
+        const search = event.url.searchParams.toString();
+        const fullPath = `/${path}${search ? `?${search}` : ''}`;
+        const isAllowed = config.allowedPaths.some((prefix) => path?.startsWith(prefix));
+        if (!isAllowed)
+            throw error(403, 'Forbidden: This API path is not allowed.');
+        const url = `${config.baseURL}${fullPath}`;
+        const headers = new Headers();
+        for (const [key, value] of event.request.headers) {
+            if (safeRequestHeaders.includes(key.toLowerCase()) && value != null) {
+                headers.set(key, value);
+            }
+        }
+        const token = config.extractToken?.(event.locals);
+        if (token)
+            headers.set('Authorization', `Bearer ${token}`);
+        const proxyResponse = await fetch(url, {
+            method: event.request.method,
+            headers,
+            body: event.request.method !== 'GET' && event.request.method !== 'HEAD'
+                ? await event.request.clone().arrayBuffer()
+                : undefined
+        });
+        const responseHeaders = new Headers();
+        for (const [key, value] of proxyResponse.headers) {
+            if (safeResponseHeaders.includes(key.toLowerCase()) && value != null) {
+                responseHeaders.set(key, value);
+            }
+        }
+        return new Response(proxyResponse.body, {
+            status: proxyResponse.status,
+            headers: responseHeaders
+        });
+    }
+    return {
+        GET: handler,
+        POST: handler,
+        PUT: handler,
+        PATCH: handler,
+        DELETE: handler,
+        OPTIONS: handler
+    };
+}

package/dist/modules/crypto.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Encrypts plaintext using AES-256-GCM.
+ * Provides confidentiality, integrity, and authenticity.
+ *
+ * @param plaintext The string to encrypt.
+ * @param secretKey The 256-bit (32-byte) secret key, base64url encoded.
+ * @returns The encrypted data (IV + Tag + Ciphertext), base64url encoded.
+ */
+export declare function encrypt(plaintext: string, secretKey: string): string;
+/**
+ * Decrypts data encrypted with AES-256-GCM.
+ * Verifies authenticity before decrypting.
+ *
+ * @param ivTagCiphertextB64 The encrypted data (IV + Tag + Ciphertext), base64url encoded.
+ * @param secretKey The 256-bit (32-byte) secret key, base64url encoded.
+ * @returns The decrypted plaintext string.
+ * @throws Error if authentication tag is invalid (data tampering) or decryption fails.
+ */
+export declare function decrypt(ivTagCiphertextB64: string, secretKey: string): string;
+/**
+ * Generates random bytes and returns them as a base64url encoded string.
+ * Useful for generating cryptographic keys or nonces.
+ *
+ * @param length The number of random bytes to generate.
+ * @returns A base64url encoded string of random bytes.
+ */
+export declare function generateRandomBytes(length: number): string;

package/dist/modules/crypto.js

@@ -0,0 +1,76 @@
+import crypto from 'node:crypto';
+// Command to generate a random 32-byte base64 key for AES-256 encryption
+// node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+/**
+ * Encrypts plaintext using AES-256-GCM.
+ * Provides confidentiality, integrity, and authenticity.
+ *
+ * @param plaintext The string to encrypt.
+ * @param secretKey The 256-bit (32-byte) secret key, base64url encoded.
+ * @returns The encrypted data (IV + Tag + Ciphertext), base64url encoded.
+ */
+export function encrypt(plaintext, secretKey) {
+    const key = Buffer.from(secretKey, 'base64url'); // Ensure key is 32 bytes after decoding
+    if (key.length !== 32) {
+        throw new Error('Secret key must be 32 bytes (256 bits) for AES-256-GCM.');
+    }
+    const iv = crypto.randomBytes(16); // Initialization Vector (IV) for GCM is 16 bytes (128 bits)
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag(); // Authentication Tag
+    // Concatenate IV, Tag, and Ciphertext for storage/transmission
+    const combined = Buffer.concat([iv, tag, encrypted]);
+    return combined.toString('base64url');
+}
+/**
+ * Decrypts data encrypted with AES-256-GCM.
+ * Verifies authenticity before decrypting.
+ *
+ * @param ivTagCiphertextB64 The encrypted data (IV + Tag + Ciphertext), base64url encoded.
+ * @param secretKey The 256-bit (32-byte) secret key, base64url encoded.
+ * @returns The decrypted plaintext string.
+ * @throws Error if authentication tag is invalid (data tampering) or decryption fails.
+ */
+export function decrypt(ivTagCiphertextB64, secretKey) {
+    const key = Buffer.from(secretKey, 'base64url'); // Ensure key is 32 bytes after decoding
+    if (key.length !== 32) {
+        throw new Error('Secret key must be 32 bytes (256 bits) for AES-256-GCM.');
+    }
+    const combined = Buffer.from(ivTagCiphertextB64, 'base64url');
+    // Extract IV (16 bytes), Tag (16 bytes), and Ciphertext
+    const iv = combined.subarray(0, 16);
+    const tag = combined.subarray(16, 32);
+    const ciphertext = combined.subarray(32);
+    if (iv.length !== 16) {
+        throw new Error('Invalid IV length: Expected 16 bytes.');
+    }
+    if (tag.length !== 16) {
+        throw new Error('Invalid Auth Tag length: Expected 16 bytes.');
+    }
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag); // Set the authentication tag for verification
+    try {
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return decrypted.toString('utf-8');
+    }
+    catch (e) {
+        // 'Bad decrypt' or 'Unsupported state or unable to authenticate data' indicates tampering or wrong key/IV/tag
+        if (e instanceof Error && (e.message.includes('Unsupported state') || e.message.includes('unable to authenticate data'))) {
+            throw new Error('Decryption failed: Data may have been tampered with or key is incorrect.');
+        }
+        throw e; // Re-throw other unexpected errors
+    }
+}
+/**
+ * Generates random bytes and returns them as a base64url encoded string.
+ * Useful for generating cryptographic keys or nonces.
+ *
+ * @param length The number of random bytes to generate.
+ * @returns A base64url encoded string of random bytes.
+ */
+export function generateRandomBytes(length) {
+    if (length <= 0) {
+        throw new Error('Length must be a positive number.');
+    }
+    return crypto.randomBytes(length).toString('base64url');
+}

package/dist/modules/problem-details.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Custom error class representing a structured Problem Details error response.
+ *
+ * This class conforms to the RFC 7807 Problem Details format with an additional `errors`
+ * field for validation-specific field errors. It is suitable for use in APIs and form
+ * validation where you want to return field-specific messages along with standard
+ * HTTP error information.
+ */
+export declare class ProblemDetailError extends Error {
+    /** HTTP status code (e.g. 400, 404, 500) */
+    status: number;
+    /** A URI reference that identifies the problem type (e.g. "/exceptions/invalid_input/") */
+    type: string;
+    /** A human-readable explanation specific to this occurrence of the problem */
+    detail: string;
+    /**
+     * A dictionary of field-specific validation errors.
+     * Example: { email: ["Invalid email address"] }
+     */
+    errors: Record<string, string[]>;
+    /**
+     * Constructs a new ProblemDetailError instance.
+     *
+     * @param field - The field name that has a validation error.
+     * @param field_error - The error message associated with the field.
+     * @param status - HTTP status code (default: 400).
+     * @param title - A short, human-readable summary of the problem (default: "Bad Request").
+     * @param type - A URI identifier for the problem type (default: "/exceptions/bad_request/").
+     */
+    constructor(field: string, field_error: string, status?: number, title?: string, type?: string);
+}

package/dist/modules/problem-details.js

@@ -0,0 +1,40 @@
+/**
+ * Custom error class representing a structured Problem Details error response.
+ *
+ * This class conforms to the RFC 7807 Problem Details format with an additional `errors`
+ * field for validation-specific field errors. It is suitable for use in APIs and form
+ * validation where you want to return field-specific messages along with standard
+ * HTTP error information.
+ */
+export class ProblemDetailError extends Error {
+    /** HTTP status code (e.g. 400, 404, 500) */
+    status;
+    /** A URI reference that identifies the problem type (e.g. "/exceptions/invalid_input/") */
+    type;
+    /** A human-readable explanation specific to this occurrence of the problem */
+    detail;
+    /**
+     * A dictionary of field-specific validation errors.
+     * Example: { email: ["Invalid email address"] }
+     */
+    errors;
+    /**
+     * Constructs a new ProblemDetailError instance.
+     *
+     * @param field - The field name that has a validation error.
+     * @param field_error - The error message associated with the field.
+     * @param status - HTTP status code (default: 400).
+     * @param title - A short, human-readable summary of the problem (default: "Bad Request").
+     * @param type - A URI identifier for the problem type (default: "/exceptions/bad_request/").
+     */
+    constructor(field, field_error, status = 400, title = "Bad Request", type = "/exceptions/bad_request/") {
+        super(title); // Call parent Error class constructor
+        this.name = "ProblemDetailError";
+        this.status = status;
+        this.type = type;
+        this.detail = "Your request contained invalid input.";
+        this.errors = {
+            [field]: [field_error]
+        };
+    }
+}

package/package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "git+https://github.com/hashrytech/quick-components-kit.git"
   },
-  "version": "0.11.1",
+  "version": "0.12.1",
   "license": "MIT",
   "author": "Hashry Tech",
   "files": [