create-request 0.0.1-beta.2 → 0.0.1-beta.4

package/dist/library/index.js

@@ -10,11 +10,11 @@
     exports.HttpMethod = void 0;
     (function (HttpMethod) {
         HttpMethod["GET"] = "GET";
-        HttpMethod["POST"] = "POST";
         HttpMethod["PUT"] = "PUT";
-        HttpMethod["DELETE"] = "DELETE";
-        HttpMethod["PATCH"] = "PATCH";
+        HttpMethod["POST"] = "POST";
         HttpMethod["HEAD"] = "HEAD";
+        HttpMethod["PATCH"] = "PATCH";
+        HttpMethod["DELETE"] = "DELETE";
         HttpMethod["OPTIONS"] = "OPTIONS";
     })(exports.HttpMethod || (exports.HttpMethod = {}));
     /**
@@ -22,8 +22,8 @@
      */
     exports.RequestPriority = void 0;
     (function (RequestPriority) {
-        RequestPriority["HIGH"] = "high";
         RequestPriority["LOW"] = "low";
+        RequestPriority["HIGH"] = "high";
         RequestPriority["AUTO"] = "auto";
     })(exports.RequestPriority || (exports.RequestPriority = {}));
     /**
@@ -31,9 +31,9 @@
      */
     exports.CredentialsPolicy = void 0;
     (function (CredentialsPolicy) {
+        CredentialsPolicy["OMIT"] = "omit";
         CredentialsPolicy["INCLUDE"] = "include";
         CredentialsPolicy["SAME_ORIGIN"] = "same-origin";
-        CredentialsPolicy["OMIT"] = "omit";
     })(exports.CredentialsPolicy || (exports.CredentialsPolicy = {}));
     /**
      * Enum for request modes
@@ -50,8 +50,8 @@
      */
     exports.RedirectMode = void 0;
     (function (RedirectMode) {
-        RedirectMode["FOLLOW"] = "follow";
         RedirectMode["ERROR"] = "error";
+        RedirectMode["FOLLOW"] = "follow";
         RedirectMode["MANUAL"] = "manual";
     })(exports.RedirectMode || (exports.RedirectMode = {}));
     /**
@@ -60,12 +60,30 @@
     exports.CacheMode = void 0;
     (function (CacheMode) {
         CacheMode["DEFAULT"] = "default";
-        CacheMode["NO_STORE"] = "no-store";
         CacheMode["RELOAD"] = "reload";
+        CacheMode["NO_STORE"] = "no-store";
         CacheMode["NO_CACHE"] = "no-cache";
         CacheMode["FORCE_CACHE"] = "force-cache";
         CacheMode["ONLY_IF_CACHED"] = "only-if-cached";
     })(exports.CacheMode || (exports.CacheMode = {}));
+    /**
+     * Enum for cookie SameSite policies
+     */
+    exports.SameSitePolicy = void 0;
+    (function (SameSitePolicy) {
+        SameSitePolicy["LAX"] = "Lax";
+        SameSitePolicy["NONE"] = "None";
+        SameSitePolicy["STRICT"] = "Strict";
+    })(exports.SameSitePolicy || (exports.SameSitePolicy = {}));
+    /**
+     * Enum for body types
+     */
+    var BodyType;
+    (function (BodyType) {
+        BodyType["JSON"] = "json";
+        BodyType["STRING"] = "string";
+        BodyType["BINARY"] = "binary";
+    })(BodyType || (BodyType = {}));
 
     class RequestError extends Error {
         constructor(message, url, method, options = {}) {
@@ -139,44 +157,241 @@
         /**
          * Parse response as JSON
          */
-        async json() {
+        async getJson() {
             return this.response.json();
         }
         /**
          * Get response as text
          */
-        async text() {
+        async getText() {
             return this.response.text();
         }
         /**
          * Get response as Blob
          */
-        async blob() {
+        async getBlob() {
             return this.response.blob();
         }
         /**
          * Get response as ArrayBuffer
          */
-        async arrayBuffer() {
+        async getArrayBuffer() {
             return this.response.arrayBuffer();
         }
         /**
-         * Get response as ReadableStream
+         * Get response as ReadableStream for true streaming consumption.
+         * This allows you to process data incrementally as it arrives.
+         *
+         * @example
+         * const stream = await request.sendTo('https://example.com/large-file').getBody();
+         * const reader = stream.getReader();
+         *
+         * while (true) {
+         *   const { done, value } = await reader.read();
+         *   if (done) break;
+         *   // Process chunk of data in 'value'
+         * }
          */
-        body() {
+        getBody() {
             return this.response.body;
         }
     }
 
+    /**
+     * Global configuration for create-request
+     */
+    class Config {
+        constructor() {
+            // CSRF configuration
+            this.csrfHeaderName = "X-CSRF-Token";
+            this.xsrfCookieName = "XSRF-TOKEN";
+            this.xsrfHeaderName = "X-XSRF-TOKEN";
+            this.csrfToken = null;
+            this.enableAutoXsrf = true;
+            this.enableAntiCsrf = true; // X-Requested-With header
+        }
+        /**
+         * Get the singleton instance
+         */
+        static getInstance() {
+            if (!Config.instance) {
+                Config.instance = new Config();
+            }
+            return Config.instance;
+        }
+        /**
+         * Set a global CSRF token to be used for all requests
+         */
+        setCsrfToken(token) {
+            this.csrfToken = token;
+            return this;
+        }
+        /**
+         * Get the global CSRF token
+         */
+        getCsrfToken() {
+            return this.csrfToken;
+        }
+        /**
+         * Set the CSRF header name (default is X-CSRF-Token)
+         */
+        setCsrfHeaderName(name) {
+            this.csrfHeaderName = name;
+            return this;
+        }
+        /**
+         * Get the CSRF header name
+         */
+        getCsrfHeaderName() {
+            return this.csrfHeaderName;
+        }
+        /**
+         * Set the XSRF cookie name to look for (default is XSRF-TOKEN)
+         */
+        setXsrfCookieName(name) {
+            this.xsrfCookieName = name;
+            return this;
+        }
+        /**
+         * Get the XSRF cookie name
+         */
+        getXsrfCookieName() {
+            return this.xsrfCookieName;
+        }
+        /**
+         * Set the XSRF header name to send the token in (default is X-XSRF-TOKEN)
+         */
+        setXsrfHeaderName(name) {
+            this.xsrfHeaderName = name;
+            return this;
+        }
+        /**
+         * Get the XSRF header name
+         */
+        getXsrfHeaderName() {
+            return this.xsrfHeaderName;
+        }
+        /**
+         * Enable or disable automatic XSRF token extraction from cookies
+         */
+        setEnableAutoXsrf(enable) {
+            this.enableAutoXsrf = enable;
+            return this;
+        }
+        /**
+         * Check if automatic XSRF is enabled
+         */
+        isAutoXsrfEnabled() {
+            return this.enableAutoXsrf;
+        }
+        /**
+         * Enable or disable automatic addition of anti-CSRF headers
+         */
+        setEnableAntiCsrf(enable) {
+            this.enableAntiCsrf = enable;
+            return this;
+        }
+        /**
+         * Check if anti-CSRF is enabled
+         */
+        isAntiCsrfEnabled() {
+            return this.enableAntiCsrf;
+        }
+        /**
+         * Reset configuration to defaults
+         */
+        reset() {
+            this.csrfToken = null;
+            this.csrfHeaderName = "X-CSRF-Token";
+            this.xsrfCookieName = "XSRF-TOKEN";
+            this.xsrfHeaderName = "X-XSRF-TOKEN";
+            this.enableAutoXsrf = true;
+            this.enableAntiCsrf = true;
+            return this;
+        }
+    }
+
+    class CookieUtils {
+        /**
+         * Formats cookies for a request
+         * @param cookies Object containing cookie name-value pairs or cookie options
+         * @returns Formatted cookie string for the Cookie header
+         */
+        static formatRequestCookies(cookies) {
+            const cookiePairs = [];
+            Object.entries(cookies).forEach(([name, valueOrOptions]) => {
+                let value;
+                if (typeof valueOrOptions === "string") {
+                    value = valueOrOptions;
+                }
+                else {
+                    // Extract value from options object without validation
+                    value = valueOrOptions.value;
+                }
+                // Add the cookie to the request
+                cookiePairs.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+            });
+            return cookiePairs.join("; ");
+        }
+    }
+
+    /**
+     * Utility class for CSRF token management
+     */
+    class CsrfUtils {
+        /**
+         * Extracts CSRF token from a meta tag in the document head
+         * @param metaName The name attribute of the meta tag (default: "csrf-token")
+         * @returns The CSRF token or null if not found
+         */
+        static getTokenFromMeta(metaName = "csrf-token") {
+            if (typeof document === "undefined") {
+                return null;
+            }
+            const meta = document.querySelector(`meta[name="${metaName}"]`);
+            return (meta === null || meta === void 0 ? void 0 : meta.getAttribute("content")) || null;
+        }
+        /**
+         * Extracts CSRF token from a cookie
+         * @param cookieName The name of the cookie containing the CSRF token
+         * @returns The CSRF token or null if not found
+         */
+        static getTokenFromCookie(cookieName = "csrf-token") {
+            if (typeof document === "undefined") {
+                return null;
+            }
+            const cookies = document.cookie.split(";");
+            for (const cookie of cookies) {
+                const [name, value] = cookie.trim().split("=");
+                if (name === cookieName) {
+                    return decodeURIComponent(value);
+                }
+            }
+            return null;
+        }
+        /**
+         * Validates if the provided string is a potential CSRF token
+         * Checks if the token meets minimum security requirements (non-empty, not too short)
+         * @param token The token to validate
+         * @returns Whether the token is potentially valid
+         */
+        static isValidToken(token) {
+            return typeof token === "string" && token.length >= 8;
+        }
+    }
+
     // Base class with common functionality for all request types
     class BaseRequest {
         constructor() {
-            this.requestOptions = {};
+            this.requestOptions = {
+                headers: {},
+            };
             this.queryParams = new URLSearchParams();
+            this.autoApplyCsrfProtection = true;
         }
         withHeaders(headers) {
             this.requestOptions.headers = {
-                ...(this.requestOptions.headers || {}),
+                ...this.requestOptions.headers,
                 ...headers,
             };
             return this;
@@ -328,7 +543,7 @@
         }
         /**
          * Sets cookies for the request
-         * @param cookies - An object containing cookie name-value pairs
+         * @param cookies Object containing cookie name-value pairs or cookie options
          * @returns The instance for chaining
          */
         withCookies(cookies) {
@@ -336,18 +551,58 @@
             if (cookieEntries.length === 0) {
                 return this;
             }
-            // Format cookies as name=value pairs
-            const cookieString = cookieEntries
-                .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`)
-                .join("; ");
             // Get current headers or initialize empty object
             const currentHeaders = this.requestOptions.headers || {};
-            // If there's already a Cookie header, append to it; otherwise create a new one
-            const existingCookies = currentHeaders["Cookie"] || "";
+            // Get the existing cookie header in a case-insensitive way
+            let existingCookies = "";
+            const cookieHeaderName = Object.keys(currentHeaders).find(header => header.toLowerCase() === "cookie");
+            if (cookieHeaderName)
+                existingCookies = currentHeaders[cookieHeaderName];
+            const cookieString = CookieUtils.formatRequestCookies(cookies);
+            // Combine with existing cookies if present
             const newCookieValue = existingCookies ? `${existingCookies}; ${cookieString}` : cookieString;
-            // Set the Cookie header
+            // Set the Cookie header, preserving original case if it exists
+            const headerName = cookieHeaderName || "Cookie";
             return this.withHeaders({
-                Cookie: newCookieValue,
+                [headerName]: newCookieValue,
+            });
+        }
+        /**
+         * Set a single cookie
+         * @param name Cookie name
+         * @param value Cookie value or options object
+         * @returns The instance for chaining
+         */
+        withCookie(name, value) {
+            return this.withCookies({ [name]: value });
+        }
+        /**
+         * Sets a CSRF token in the request headers
+         * @param token The CSRF token
+         * @param headerName The name of the header to use (default: X-CSRF-Token)
+         * @returns The instance for chaining
+         */
+        withCsrfToken(token, headerName = "X-CSRF-Token") {
+            return this.withHeaders({
+                [headerName]: token,
+            });
+        }
+        /**
+         * Disables automatic anti-CSRF protection.
+         * By default, X-Requested-With: XMLHttpRequest header is sent with all requests.
+         * @returns The instance for chaining
+         */
+        withoutCsrfProtection() {
+            this.autoApplyCsrfProtection = false;
+            return this;
+        }
+        /**
+         * Sets common security headers to help prevent CSRF attacks
+         * @returns The instance for chaining
+         */
+        withAntiCsrfHeaders() {
+            return this.withHeaders({
+                "X-Requested-With": "XMLHttpRequest",
             });
         }
         /**
@@ -357,6 +612,41 @@
         sendTo(url) {
             // Format the URL with query parameters
             url = this.formatUrlWithQueryParams(url);
+            // Apply automatic CSRF protection if enabled
+            if (this.autoApplyCsrfProtection) {
+                const config = Config.getInstance();
+                // Apply anti-CSRF headers if enabled
+                if (config.isAntiCsrfEnabled()) {
+                    this.withHeaders({
+                        "X-Requested-With": "XMLHttpRequest",
+                    });
+                }
+                // Apply global CSRF token if set
+                const globalToken = config.getCsrfToken();
+                if (globalToken) {
+                    // Check if local token exists
+                    const headers = this.requestOptions.headers;
+                    const hasLocalToken = Object.keys(headers).some(key => key === "X-CSRF-Token" || key === config.getCsrfHeaderName());
+                    if (!hasLocalToken) {
+                        this.withHeaders({
+                            [config.getCsrfHeaderName()]: globalToken,
+                        });
+                    }
+                }
+                // check for XSRF token in cookies and send it as a header
+                if (config.isAutoXsrfEnabled() && typeof document !== "undefined") {
+                    const xsrfToken = CsrfUtils.getTokenFromCookie(config.getXsrfCookieName());
+                    if (xsrfToken && CsrfUtils.isValidToken(xsrfToken)) {
+                        const headers = this.requestOptions.headers;
+                        const hasLocalToken = Object.keys(headers).some(key => key === "X-XSRF-TOKEN" || key === config.getXsrfHeaderName());
+                        if (!hasLocalToken) {
+                            this.withHeaders({
+                                [config.getXsrfHeaderName()]: xsrfToken,
+                            });
+                        }
+                    }
+                }
+            }
             // Cast the request options to RequestInit to ensure compatibility
             const fetchOptions = {
                 ...this.requestOptions,
@@ -366,28 +656,22 @@
             const basePromise = !this.requestOptions.retries
                 ? this.executeRequest(url, fetchOptions)
                 : this.executeWithRetries(url, fetchOptions);
-            // Enhance the promise with response methods
-            const responsePromise = basePromise.then(response => response);
-            // Attach convenience methods to the promise
-            responsePromise.json = async () => {
-                const response = await basePromise;
-                return response.json();
+            const responsePromise = basePromise;
+            // Attach convenience methods that begin processing immediately
+            responsePromise.getJson = async () => {
+                return basePromise.then(response => response.getJson());
             };
-            responsePromise.text = async () => {
-                const response = await basePromise;
-                return response.text();
+            responsePromise.getText = async () => {
+                return basePromise.then(response => response.getText());
             };
-            responsePromise.blob = async () => {
-                const response = await basePromise;
-                return response.blob();
+            responsePromise.getBlob = async () => {
+                return basePromise.then(response => response.getBlob());
             };
-            responsePromise.arrayBuffer = async () => {
-                const response = await basePromise;
-                return response.arrayBuffer();
+            responsePromise.getArrayBuffer = async () => {
+                return basePromise.then(response => response.getArrayBuffer());
             };
-            responsePromise.body = async () => {
-                const response = await basePromise;
-                return response.body();
+            responsePromise.getBody = async () => {
+                return basePromise.then(response => response.getBody());
             };
             return responsePromise;
         }
@@ -414,7 +698,7 @@
          * @returns A wrapped response object
          */
         async executeWithRetries(url, fetchOptions) {
-            let retryCount = 0;
+            let attempt = 0;
             const maxRetries = this.requestOptions.retries || 0;
             // eslint-disable-next-line no-constant-condition
             while (true) {
@@ -425,12 +709,12 @@
                     const requestError = error instanceof RequestError
                         ? error
                         : RequestError.networkError(url, fetchOptions.method, error);
-                    if (retryCount >= maxRetries || requestError.timeoutError) {
+                    if (attempt >= maxRetries || requestError.timeoutError) {
                         throw requestError;
                     }
-                    retryCount++;
+                    attempt++;
                     if (this.requestOptions.onRetry) {
-                        await this.requestOptions.onRetry({ retryCount, error: requestError });
+                        await this.requestOptions.onRetry({ attempt, error: requestError });
                     }
                 }
             }
@@ -476,47 +760,72 @@
         }
     }
 
-    // An extension of BaseRequest for methods that support request bodies
+    /**
+     * Base class for requests that can have a body (POST, PUT, PATCH)
+     */
     class BodyRequest extends BaseRequest {
+        constructor() {
+            super(...arguments);
+            this.bodyProcessed = false;
+        }
         /**
-         * Sets the request body with appropriate content type handling
+         * Sets the body of the request
+         * @param body - The request body
          */
         withBody(body) {
-            if (body === undefined || body === null) {
-                this.requestOptions.body = null;
-                return this;
-            }
-            // Handle special body types that don't need transformation
-            if (body instanceof Blob ||
-                body instanceof FormData ||
-                body instanceof URLSearchParams ||
-                body instanceof ArrayBuffer ||
-                body instanceof ReadableStream) {
-                this.requestOptions.body = body;
-                // For FormData, make sure to NOT explicitly set Content-Type
-                // The browser will set it automatically with the correct boundary
-                // If we set it manually, it would be missing the boundary parameter
-                return this;
-            }
-            // Handle strings
+            this.body = body;
+            this.bodyProcessed = false;
+            // Set body type and validate
             if (typeof body === "string") {
-                this.requestOptions.body = body;
-                return this;
+                this.bodyType = BodyType.STRING;
+                this.setContentTypeIfNeeded("text/plain");
             }
-            // For objects and other types, stringify and set JSON content-type
-            try {
-                this.requestOptions.body = JSON.stringify(body);
-                this.requestOptions.headers = {
-                    "Content-Type": "application/json",
-                    ...(this.requestOptions.headers || {}),
-                };
+            else if (body !== null &&
+                typeof body === "object" &&
+                !(body instanceof FormData ||
+                    body instanceof Blob ||
+                    body instanceof ArrayBuffer ||
+                    body instanceof URLSearchParams ||
+                    body instanceof ReadableStream)) {
+                this.bodyType = BodyType.JSON;
+                this.setContentTypeIfNeeded("application/json");
+                // Validate JSON is stringifiable early
+                try {
+                    JSON.stringify(body);
+                }
+                catch (error) {
+                    throw new Error(`Failed to stringify request body: ${String(error)}`);
+                }
             }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                throw new Error(`Failed to stringify request body: ${errorMessage}`);
+            else {
+                this.bodyType = BodyType.BINARY;
             }
             return this;
         }
+        setContentTypeIfNeeded(contentType) {
+            // Only set if not already set
+            const headers = this.requestOptions.headers;
+            if (!Object.keys(headers).some(header => header.toLowerCase() === "content-type")) {
+                this.withContentType(contentType);
+            }
+        }
+        /**
+         * Send the request to the specified URL
+         * Overrides the base implementation to add body handling
+         */
+        sendTo(url) {
+            // Process body only once
+            if (!this.bodyProcessed && this.body !== undefined && !this.requestOptions.body) {
+                if (this.bodyType === BodyType.JSON) {
+                    this.requestOptions.body = JSON.stringify(this.body);
+                }
+                else {
+                    this.requestOptions.body = this.body;
+                }
+                this.bodyProcessed = true;
+            }
+            return super.sendTo(url);
+        }
     }
 
     // Methods without body
@@ -608,7 +917,7 @@
         return new OptionsRequest();
     }
 
-    // Create the main API object
+    // Create the main API object with configuration
     const create = {
         get,
         post,
@@ -617,8 +926,11 @@
         patch,
         head,
         options,
+        // Add configuration access
+        config: Config.getInstance(),
     };
 
+    exports.CookieUtils = CookieUtils;
     exports.DeleteRequest = DeleteRequest;
     exports.GetRequest = GetRequest;
     exports.HeadRequest = HeadRequest;

package/dist/library/types.d.ts

@@ -1,11 +1,22 @@
-import { HttpMethod, RequestPriority, CredentialsPolicy, RequestMode, RedirectMode, CacheMode } from "./enums";
+import { HttpMethod, RequestPriority, CredentialsPolicy, RequestMode, RedirectMode, CacheMode, SameSitePolicy } from "./enums";
 import type { RequestError } from "./RequestError";
 export type Body = null | Blob | string | object | FormData | ArrayBuffer | URLSearchParams | ReadableStream;
 export type RetryCallback = (options: {
-    retryCount: number;
+    attempt: number;
     error: RequestError;
 }) => void | Promise<void>;
-export { HttpMethod, RequestPriority, CredentialsPolicy, RequestMode, RedirectMode, CacheMode };
+export interface CookieOptions {
+    value: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: SameSitePolicy;
+    expires?: Date;
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+}
+export type CookiesRecord = Record<string, string | CookieOptions>;
+export { CacheMode, HttpMethod, RequestMode, RedirectMode, SameSitePolicy, RequestPriority, CredentialsPolicy, };
 export interface RequestOptions extends Omit<RequestInit, "signal" | "body" | "method" | "credentials" | "mode" | "redirect" | "cache" | "priority"> {
     timeout?: number;
     retries?: number;