create-request 1.4.3-rc.1 → 1.4.3-rc.3

package/dist/library/BaseRequest.d.ts

@@ -365,16 +365,56 @@ export declare abstract class BaseRequest {
         ONLY_IF_CACHED: () => BaseRequest;
     };
     /**
-     * Adds query parameters to the request URL
-     * @param params - An object containing the query parameters
-     * @returns The instance for chaining
+     * Adds query parameters to the request URL.
+     * Multiple calls will append parameters. Array values will create multiple query parameters with the same key.
+     * Null and undefined values are ignored.
+     *
+     * @param params - An object containing query parameter key-value pairs.
+     *   Values can be strings, numbers, booleans, arrays (for multiple values), or null/undefined (ignored).
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple parameters
+     * request.withQueryParams({ page: 1, limit: 10, active: true });
+     * // Results in: ?page=1&limit=10&active=true
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Array values create multiple parameters
+     * request.withQueryParams({ tags: ['js', 'ts', 'node'] });
+     * // Results in: ?tags=js&tags=ts&tags=node
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Null/undefined values are ignored
+     * request.withQueryParams({ page: 1, filter: null, sort: undefined });
+     * // Results in: ?page=1
+     * ```
      */
     withQueryParams(params: Record<string, string | string[] | number | boolean | null | undefined>): this;
     /**
-     * Adds a single query parameter
-     * @param key - The parameter name
-     * @param value - The parameter value, can be a single value or array of values
-     * @returns The instance for chaining
+     * Adds a single query parameter to the request URL.
+     * Convenience method for adding one parameter at a time.
+     *
+     * @param key - The query parameter name
+     * @param value - The query parameter value. Can be a string, number, boolean, array (for multiple values), or null/undefined (ignored).
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withQueryParam('page', 1).withQueryParam('limit', 10);
+     * // Results in: ?page=1&limit=10
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Array values create multiple parameters
+     * request.withQueryParam('tags', ['js', 'ts']);
+     * // Results in: ?tags=js&tags=ts
+     * ```
      */
     withQueryParam(key: string, value: string | string[] | number | boolean | null | undefined): this;
     /**
@@ -412,22 +452,55 @@ export declare abstract class BaseRequest {
         NAVIGATE: () => BaseRequest;
     };
     /**
-     * Shorthand for setting the Content-Type header
-     * @param contentType - The content type
-     * @returns The instance for chaining
+     * Sets the Content-Type header for the request.
+     * Shorthand for `withHeader('Content-Type', contentType)`.
+     *
+     * @param contentType - The MIME type (e.g., `'application/json'`, `'text/plain'`, `'multipart/form-data'`)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withContentType('application/json');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withContentType('application/xml');
+     * ```
      */
     withContentType(contentType: string): this;
     /**
-     * Shorthand for setting the Authorization header
-     * @param authValue - The authorization value
-     * @returns The instance for chaining
+     * Sets the Authorization header for the request.
+     * Shorthand for `withHeader('Authorization', authValue)`.
+     * For Bearer tokens, use `withBearerToken()` instead. For Basic auth, use `withBasicAuth()`.
+     *
+     * @param authValue - The full authorization header value (e.g., `'Bearer token123'`, `'Basic base64string'`)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withAuthorization('Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withAuthorization('CustomScheme customToken');
+     * ```
      */
     withAuthorization(authValue: string): this;
     /**
-     * Shorthand for setting up Basic authentication
-     * @param username - The username
-     * @param password - The password
-     * @returns The instance for chaining
+     * Sets up HTTP Basic Authentication.
+     * Encodes the username and password in base64 and sets the Authorization header.
+     *
+     * @param username - The username for Basic authentication
+     * @param password - The password for Basic authentication
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withBasicAuth('myuser', 'mypassword');
+     * // Sets: Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ=
+     * ```
      */
     withBasicAuth(username: string, password: string): this;
     /**
@@ -436,9 +509,17 @@ export declare abstract class BaseRequest {
      */
     private encodeBase64;
     /**
-     * Sets the bearer token for authentication
-     * @param token - The bearer token
-     * @returns The instance for chaining
+     * Sets a Bearer token for authentication.
+     * Shorthand for `withAuthorization('Bearer ' + token)`.
+     *
+     * @param token - The Bearer token (JWT, OAuth token, etc.)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withBearerToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+     * // Sets: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+     * ```
      */
     withBearerToken(token: string): this;
     /**
@@ -453,23 +534,69 @@ export declare abstract class BaseRequest {
      */
     private hasHeader;
     /**
-     * Sets cookies for the request
-     * @param cookies Object containing cookie name-value pairs or cookie options
-     * @returns The instance for chaining
+     * Sets cookies for the request.
+     * Cookies are sent in the Cookie header. Multiple calls will merge cookies.
+     * Cookie values can be simple strings or objects with additional cookie options.
+     *
+     * @param cookies - An object where keys are cookie names and values are either:
+     *   - A string (the cookie value)
+     *   - A CookieOptions object with `value` and optional properties (secure, httpOnly, sameSite, expires, path, domain, maxAge)
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple string cookies
+     * request.withCookies({ sessionId: 'abc123', userId: '456' });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cookies with options (note: options are for documentation only in request cookies)
+     * request.withCookies({
+     *   sessionId: 'abc123',
+     *   token: { value: 'xyz789', secure: true }
+     * });
+     * ```
      */
     withCookies(cookies: CookiesRecord): this;
     /**
-     * Set a single cookie
-     * @param name Cookie name
-     * @param value Cookie value or options object
-     * @returns The instance for chaining
+     * Sets a single cookie for the request.
+     * Convenience method for adding one cookie at a time.
+     *
+     * @param name - The cookie name
+     * @param value - The cookie value as a string, or a CookieOptions object with `value` and optional properties
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withCookie('sessionId', 'abc123');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withCookie('token', { value: 'xyz789', secure: true });
+     * ```
      */
     withCookie(name: string, value: string | CookieOptions): this;
     /**
-     * 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
+     * Sets a CSRF (Cross-Site Request Forgery) token in the request headers.
+     * This is commonly used to protect against CSRF attacks in web applications.
+     *
+     * @param token - The CSRF token value
+     * @param headerName - The name of the header to use. Defaults to `'X-CSRF-Token'`.
+     * @returns The request instance for chaining
+     *
+     * @example
+     * ```typescript
+     * request.withCsrfToken('csrf-token-123');
+     * // Sets: X-CSRF-Token: csrf-token-123
+     * ```
+     *
+     * @example
+     * ```typescript
+     * request.withCsrfToken('token', 'X-Custom-CSRF-Header');
+     * // Sets: X-Custom-CSRF-Header: token
+     * ```
      */
     withCsrfToken(token: string, headerName?: string): this;
     /**
@@ -557,30 +684,48 @@ export declare abstract class BaseRequest {
      */
     getJson<T = unknown>(): Promise<T>;
     /**
-     * Execute the request and get the response as text
+     * Execute the request and get the response body as text.
      *
-     * @returns A promise that resolves to the response text
+     * @returns A promise that resolves to the response body as a string
+     * @throws {RequestError} When the request fails or reading the response fails
      *
      * @example
+     * ```typescript
      * const text = await request.getText();
+     * console.log(text); // "Hello, world!"
+     * ```
      */
     getText(): Promise<string>;
     /**
-     * Execute the request and get the response as a Blob
+     * Execute the request and get the response body as a Blob.
+     * Useful for downloading files or handling binary data.
      *
-     * @returns A promise that resolves to the response Blob
+     * @returns A promise that resolves to the response body as a Blob
+     * @throws {RequestError} When the request fails or reading the response fails
      *
      * @example
+     * ```typescript
      * const blob = await request.getBlob();
+     * const url = URL.createObjectURL(blob);
+     * // Use the blob URL (e.g., for downloading or displaying)
+     * ```
      */
     getBlob(): Promise<Blob>;
     /**
-     * Execute the request and get the response body as a ReadableStream
+     * Execute the request and get the response body as a ReadableStream.
+     * Note: Unlike other methods, streams cannot be cached. The body can only be consumed once.
      *
-     * @returns A promise that resolves to the response body stream
+     * @returns A promise that resolves to the response body as a ReadableStream, or `null` if the body is not available
+     * @throws {RequestError} When the request fails or the body has already been consumed
      *
      * @example
+     * ```typescript
      * const stream = await request.getBody();
+     * if (stream) {
+     *   const reader = stream.getReader();
+     *   // Process the stream chunk by chunk
+     * }
+     * ```
      */
     getBody(): Promise<ReadableStream<Uint8Array> | null>;
     /**

package/dist/library/BodyRequest.d.ts

@@ -10,31 +10,77 @@ export declare abstract class BodyRequest extends BaseRequest {
     private graphQLOptions;
     constructor(url: string);
     /**
-     * Sets the body of the request
-     * @param body - The request body
+     * Sets the request body. Automatically detects the body type and sets appropriate Content-Type header.
+     * Supports JSON objects/arrays, strings, FormData, Blob, ArrayBuffer, URLSearchParams, and ReadableStream.
+     *
+     * @param body - The request body. Can be:
+     *   - A JSON-serializable object or array (automatically stringified)
+     *   - A string (sets Content-Type to `text/plain` if not already set)
+     *   - FormData, Blob, File, ArrayBuffer, TypedArray, URLSearchParams, or ReadableStream
+     * @returns The request instance for chaining
+     * @throws {RequestError} If the body is a JSON object that cannot be stringified
+     *
+     * @example
+     * ```typescript
+     * // JSON object (automatically stringified)
+     * request.withBody({ name: 'John', age: 30 });
+     *
+     * @example
+     * // JSON array
+     * request.withBody([1, 2, 3]);
+     *
+     * @example
+     * // String
+     * request.withBody('plain text');
+     *
+     * @example
+     * // FormData
+     * const formData = new FormData();
+     * formData.append('file', fileBlob);
+     * request.withBody(formData);
+     *
+     * @example
+     * // Blob
+     * request.withBody(new Blob(['content'], { type: 'text/plain' }));
+     * ```
      */
     withBody(body: Body): this;
     /**
-     * Sets a GraphQL query or mutation as the request body
-     * Automatically formats the body as JSON and sets Content-Type to application/json
+     * Sets a GraphQL query or mutation as the request body.
+     * Automatically formats the body as JSON and sets Content-Type to `application/json`.
+     * If `throwOnError` is enabled in options, the response will be checked for GraphQL errors
+     * and a RequestError will be thrown if any are found.
      *
-     * @param query - The GraphQL query or mutation string
-     * @param variables - Optional variables object to pass with the query
+     * @param query - The GraphQL query or mutation string (e.g., `'query { user { id } }'`)
+     * @param variables - Optional variables object to pass with the query. Must be a plain object.
      * @param options - Optional GraphQL-specific options
+     * @param options.throwOnError - If `true`, throws a RequestError when the GraphQL response contains errors
      * @returns The request instance for chaining
+     * @throws {RequestError} If the query is empty, variables is invalid, or JSON stringification fails
      *
      * @example
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Simple query with variables
+     * const request = create.post('/graphql')
      *   .withGraphQL('query { user(id: $id) { name email } }', { id: '123' });
+     * const data = await request.getJson();
+     * ```
      *
      * @example
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Mutation with variables
+     * const request = create.post('/graphql')
      *   .withGraphQL('mutation { createUser(name: $name) { id } }', { name: 'John' });
+     * ```
      *
      * @example
-     * // Throw an error if the GraphQL response contains errors
-     * const request = new PostRequest('/graphql')
+     * ```typescript
+     * // Throw error if GraphQL response contains errors
+     * const request = create.post('/graphql')
      *   .withGraphQL('query { user { id } }', undefined, { throwOnError: true });
+     * // If the response has errors, this will throw a RequestError
+     * const data = await request.getJson();
+     * ```
      */
     withGraphQL(query: string, variables?: Record<string, unknown>, options?: GraphQLOptions): this;
     /**

package/dist/library/RequestError.d.ts

@@ -1,10 +1,47 @@
+/**
+ * Error class for HTTP request failures.
+ * Extends the standard Error class with additional context about the failed request.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await create.get('/api/users').getJson();
+ * } catch (error) {
+ *    console.log(`Request failed: ${error.message}`);
+ *    console.log(`URL: ${error.url}`);
+ *    console.log(`Method: ${error.method}`);
+ *    console.log(`Status: ${error.status}`);
+ *    console.log(`Is timeout: ${error.isTimeout}`);
+ *    console.log(`Is aborted: ${error.isAborted}`);
+ * }
+ * ```
+ */
 export declare class RequestError extends Error {
+    /** HTTP status code if the request received a response (e.g., 404, 500) */
     readonly status?: number;
+    /** The Response object if the request received a response before failing */
     readonly response?: Response;
+    /** The URL that was requested */
     readonly url: string;
+    /** The HTTP method that was used (e.g., 'GET', 'POST') */
     readonly method: string;
+    /** Whether the request failed due to a timeout */
     readonly isTimeout?: boolean;
+    /** Whether the request was aborted (cancelled) */
     readonly isAborted?: boolean;
+    /**
+     * Creates a new RequestError instance.
+     *
+     * @param message - Error message describing what went wrong
+     * @param url - The URL that was requested
+     * @param method - The HTTP method that was used
+     * @param options - Additional error context
+     * @param options.status - HTTP status code if available
+     * @param options.response - The Response object if available
+     * @param options.isTimeout - Whether this was a timeout error
+     * @param options.isAborted - Whether the request was aborted
+     * @param options.cause - The underlying error that caused this error
+     */
     constructor(message: string, url: string, method: string, options?: {
         status?: number;
         response?: Response;
@@ -13,10 +50,71 @@ export declare class RequestError extends Error {
         cause?: Error;
     });
     /**
-     * Static methods for creating specific types of RequestError
+     * Creates a RequestError for a timeout failure.
+     *
+     * @param url - The URL that timed out
+     * @param method - The HTTP method that was used
+     * @param timeoutMs - The timeout duration in milliseconds
+     * @returns A RequestError with `isTimeout` set to `true`
+     *
+     * @example
+     * ```typescript
+     * throw RequestError.timeout('/api/data', 'GET', 5000);
+     * ```
      */
     static timeout(url: string, method: string, timeoutMs: number): RequestError;
+    /**
+     * Creates a RequestError from an HTTP error response.
+     * Used when the server returns a non-2xx status code.
+     *
+     * @param response - The Response object from the failed request
+     * @param url - The URL that was requested
+     * @param method - The HTTP method that was used
+     * @returns A RequestError with the status code and response object
+     *
+     * @example
+     * ```typescript
+     * const response = await fetch('/api/users');
+     * if (!response.ok) {
+     *   throw RequestError.fromResponse(response, '/api/users', 'GET');
+     * }
+     * ```
+     */
     static fromResponse(response: Response, url: string, method: string): RequestError;
+    /**
+     * Creates a RequestError from a network-level error.
+     * Automatically detects and categorizes common network errors (timeouts, DNS errors, connection errors).
+     *
+     * @param url - The URL that failed
+     * @param method - The HTTP method that was used
+     * @param originalError - The original error that occurred (e.g., from fetch)
+     * @returns A RequestError with enhanced error message and context
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await fetch('/api/data');
+     * } catch (error) {
+     *   if (error instanceof Error) {
+     *     throw RequestError.networkError('/api/data', 'GET', error);
+     *   }
+     * }
+     * ```
+     */
     static networkError(url: string, method: string, originalError: Error): RequestError;
+    /**
+     * Creates a RequestError for an aborted (cancelled) request.
+     *
+     * @param url - The URL that was aborted
+     * @param method - The HTTP method that was used
+     * @returns A RequestError with `isAborted` set to `true`
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     * controller.abort();
+     * throw RequestError.abortError('/api/data', 'GET');
+     * ```
+     */
     static abortError(url: string, method: string): RequestError;
 }

package/dist/library/ResponseWrapper.d.ts

@@ -1,9 +1,22 @@
 import type { GraphQLOptions } from "./types.js";
 /**
- * Wrapper for HTTP responses with methods to transform the response data
+ * Wrapper for HTTP responses with methods to transform the response data.
+ * Provides convenient methods to parse the response body in different formats.
+ * Response bodies are cached after the first read, so you can call multiple methods
+ * (e.g., `getJson()` and `getText()`) on the same response.
+ *
+ * @example
+ * ```typescript
+ * const response = await create.get('/api/users').getResponse();
+ * console.log(response.status); // 200
+ * console.log(response.ok); // true
+ * const data = await response.getJson();
+ * ```
  */
 export declare class ResponseWrapper {
+    /** The URL that was requested (if available) */
     readonly url?: string;
+    /** The HTTP method that was used (if available) */
     readonly method?: string;
     private readonly response;
     private graphQLOptions?;
@@ -12,10 +25,26 @@ export declare class ResponseWrapper {
     private cachedJson?;
     private cachedArrayBuffer?;
     constructor(response: Response, url?: string, method?: string, graphQLOptions?: GraphQLOptions);
+    /**
+     * HTTP status code (e.g., 200, 404, 500)
+     */
     get status(): number;
+    /**
+     * HTTP status text (e.g., "OK", "Not Found", "Internal Server Error")
+     */
     get statusText(): string;
+    /**
+     * Response headers as a Headers object
+     */
     get headers(): Headers;
+    /**
+     * Whether the response status is in the 200-299 range (successful)
+     */
     get ok(): boolean;
+    /**
+     * The raw Response object from the fetch API.
+     * Use this if you need direct access to the underlying Response.
+     */
     get raw(): Response;
     /**
      * Check if the response body has already been consumed and throw an error if so
@@ -51,35 +80,49 @@ export declare class ResponseWrapper {
      */
     getJson<T = unknown>(): Promise<T>;
     /**
-     * Get the response body as text
+     * Get the response body as text.
+     * The result is cached, so subsequent calls return the same value without re-reading the body.
      *
-     * @returns The response text
-     * @throws {RequestError} When reading fails
+     * @returns A promise that resolves to the response body as a string
+     * @throws {RequestError} When the body has already been consumed or reading fails
      *
      * @example
+     * ```typescript
      * const text = await response.getText();
+     * console.log(text); // "Hello, world!"
+     * ```
      */
     getText(): Promise<string>;
     /**
-     * Get the response body as a Blob
+     * Get the response body as a Blob.
+     * Useful for downloading files or handling binary data.
+     * The result is cached, so subsequent calls return the same value without re-reading the body.
      *
-     * @returns The response as a Blob
-     * @throws {RequestError} When reading fails
+     * @returns A promise that resolves to the response body as a Blob
+     * @throws {RequestError} When the body has already been consumed or reading fails
      *
      * @example
+     * ```typescript
      * const blob = await response.getBlob();
      * const url = URL.createObjectURL(blob);
+     * // Use the blob URL for downloading or displaying
+     * ```
      */
     getBlob(): Promise<Blob>;
     /**
-     * Get the response body as an ArrayBuffer
+     * Get the response body as an ArrayBuffer.
+     * Useful for processing binary data at a low level.
+     * The result is cached, so subsequent calls return the same value without re-reading the body.
      *
-     * @returns The response as an ArrayBuffer
-     * @throws {RequestError} When reading fails
+     * @returns A promise that resolves to the response body as an ArrayBuffer
+     * @throws {RequestError} When the body has already been consumed or reading fails
      *
      * @example
+     * ```typescript
      * const buffer = await response.getArrayBuffer();
      * const uint8Array = new Uint8Array(buffer);
+     * // Process the binary data
+     * ```
      */
     getArrayBuffer(): Promise<ArrayBuffer>;
     /**

package/dist/library/apiBuilder.d.ts

@@ -20,8 +20,6 @@ interface ApiBuilderRequestMethods {
     withCookie(name: string, value: string | CookieOptions): ApiBuilder;
     withRequestInterceptor(interceptor: RequestInterceptor): ApiBuilder;
     withResponseInterceptor(interceptor: ResponseInterceptor): ApiBuilder;
-    withQueryParam(key: string, value: string | string[] | number | boolean | null | undefined): ApiBuilder;
-    withQueryParams(params: Record<string, string | string[] | number | boolean | null | undefined>): ApiBuilder;
 }
 /**
  * API builder for creating configured API instances with default settings.