@faasjs/react 8.0.0-beta.7 → 8.0.0-beta.9

package/dist/index.d.ts

@@ -1,117 +1,838 @@
-import { BaseUrl, FaasBrowserClient, Options, Options as Options$1, Response, Response as Response$1, ResponseError, ResponseError as ResponseError$1, ResponseHeaders } from "@faasjs/browser";
 import * as react from "react";
 import { Component, ComponentProps, ComponentType, Dispatch, ErrorInfo, JSX, JSXElementConstructor, ReactElement, ReactNode, RefObject, SetStateAction } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { FaasAction, FaasAction as FaasAction$1, FaasActionUnionType, FaasActionUnionType as FaasActionUnionType$1, FaasData, FaasData as FaasData$1, FaasParams, FaasParams as FaasParams$1 } from "@faasjs/types";
 
-//#region ../types/src/index.d.ts
+//#region src/generateId.d.ts
 /**
- * Interface for defining FaasJS actions.
+ * Generate random id with prefix
+ *
+ * @param prefix prefix of id
+ * @param length length of id without prefix, range is 8 ~ 18, default is 18
  *
  * @example
- * ```typescript
- * declare module '@faasjs/types' {
- *   interface FaasActions {
- *     demo: {
- *       Params: {
- *         key: string
- *       }
- *       Data: {
- *         value: string
- *       }
- *     }
+ * ```ts
+ * generateId('prefix-') // prefix-1z3b4c5d6e
+ * ```
+ */
+declare function generateId(prefix?: string, length?: number): string;
+//#endregion
+//#region src/browser.d.ts
+/**
+ * Template literal type for URL strings that must end with a forward slash.
+ *
+ * Ensures that base URLs used in FaasJS requests always have a trailing '/' character,
+ * which is required for proper URL construction when appending action paths.
+ *
+ * @remarks
+ * - Type only accepts strings ending with '/' (e.g., 'https://api.example.com/', '/')
+ * - Strings without trailing '/' will fail TypeScript type checking
+ * - Used by FaasBrowserClient constructor and Options type
+ * - Ensures consistent URL formatting across the codebase
+ * - Throws Error at runtime if baseUrl doesn't end with '/'
+ *
+ * @see FaasBrowserClient for usage in client creation
+ * @see Options for usage in request options
+ */
+type BaseUrl = `${string}/`;
+/**
+ * Configuration options for FaasJS requests.
+ *
+ * Extends the standard RequestInit interface with FaasJS-specific options for
+ * customizing request behavior, adding request hooks, and overriding defaults.
+ *
+ * @remarks
+ * - Options can be provided at client creation (defaultOptions) or per-request
+ * - Per-request options override client default options
+ * - headers are merged: per-request headers override default headers
+ * - beforeRequest hook is called before the request is sent, allowing modification
+ * - Custom request function completely replaces the default fetch implementation
+ * - baseUrl in options overrides the client's baseUrl for this specific request
+ * - When stream is true, returns the native fetch Response instead of wrapped Response
+ *
+ * @property {Record<string, string>} [headers] - Default headers to include in all requests.
+ *   Merged with client default headers, with per-request headers taking precedence.
+ *   Common headers include Content-Type, Authorization, and custom application headers.
+ *
+ * @property {Function} [beforeRequest] - Async hook called before sending each request.
+ *   Receives action, params, options, and headers, allowing modification before the request is sent.
+ *   Useful for logging, authentication, adding timestamps, or modifying headers dynamically.
+ *   Any changes to the headers object will affect the actual request.
+ *
+ * @property {Function} [request] - Custom request function to replace the default fetch.
+ *   Allows using alternative HTTP clients like axios, XMLHttpRequest, or custom implementations.
+ *   Receives the URL and parsed options, must return a Promise resolving to a Response object.
+ *   When provided, this function is used instead of the native fetch API.
+ *
+ * @property {BaseUrl} [baseUrl] - Optional override for the base URL for this specific request.
+ *   If provided, overrides the client's baseUrl. Must end with '/'.
+ *   Useful for making requests to different endpoints or environments from the same client instance.
+ *
+ * @property {boolean} [stream] - Enable streaming mode for large responses.
+ *   When true, returns the raw fetch Response object instead of a wrapped Response.
+ *   Useful for processing large data incrementally or working with binary data streams.
+ *   When false or undefined, returns a wrapped Response with automatic JSON parsing.
+ *
+ * @extends RequestInit
+ * @see FaasBrowserClient for client creation
+ * @see Response for response object structure
+ */
+type Options = RequestInit & {
+  headers?: Record<string, string>; /** trigger before request */
+  beforeRequest?: ({
+    action,
+    params,
+    options,
+    headers
+  }: {
+    action: string;
+    params?: Record<string, any> | undefined;
+    options: Options;
+    headers: Record<string, string>;
+  }) => Promise<void>; /** custom request */
+  request?: <PathOrData extends FaasActionUnionType$1>(url: string, options: Options) => Promise<Response<FaasData$1<PathOrData>>>;
+  baseUrl?: BaseUrl;
+  stream?: boolean;
+};
+/**
+ * Simple key-value object for HTTP response headers.
+ *
+ * Represents headers as a plain object with string keys and string values.
+ * Used by Response, ResponseError, and Options types.
+ *
+ * @property {string} [key] - Dynamic string keys for header names (e.g., 'Content-Type', 'Authorization').
+ *   Values must be strings. Multiple values for the same key are not supported.
+ *
+ * @remarks
+ * - Headers are case-insensitive in HTTP but stored with exact casing in this object
+ * - Common headers include: Content-Type, Authorization, X-Request-Id, X-Custom-Header
+ * - No support for multi-value headers (use comma-separated values instead)
+ * - Used in Response, ResponseError, and Options types
+ * - Simplified model compared to browser's Headers interface (no .get(), .set() methods)
+ *
+ * @see Response for usage in response objects
+ * @see ResponseError for usage in error objects
+ * @see Options for usage in request options
+ */
+type ResponseHeaders = {
+  [key: string]: string;
+};
+/**
+ * Type definition for the FaasBrowserClient.action method.
+ *
+ * Defines the signature of the method used to make requests to FaasJS functions.
+ * Provides type-safe parameter and return value handling.
+ *
+ * @template PathOrData - The function path or data type for type safety
+ *
+ * @param {FaasAction<PathOrData>} action - The function path to call
+ * @param {FaasParams<PathOrData>} [params] - Optional parameters for the function
+ * @param {Options} [options] - Optional request options
+ *
+ * @returns {Promise<Response<FaasData<PathOrData>> | Response>} - A Promise resolving to a Response object
+ *
+ * @remarks
+ * - Used internally by FaasBrowserClient.action method
+ * - Provides type-safe action method signature
+ * - Return type includes both typed and untyped Response variants
+ * - Params are optional and can be undefined
+ * - Options override client defaults when provided
+ *
+ * @see FaasBrowserClient for the class that uses this type
+ * @see Response for the return type
+ * @see Options for the options parameter type
+ */
+type FaasBrowserClientAction = <PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params?: FaasParams$1<PathOrData>, options?: Options) => Promise<Response<FaasData$1<PathOrData>> | Response>;
+/**
+ * Properties for creating a Response object.
+ *
+ * Defines the structure of response data that can be passed to the Response constructor
+ * or returned from mock handlers.
+ *
+ * @template T - The type of the data property for type-safe response creation
+ *
+ * @property {number} [status] - The HTTP status code for the response.
+ *   Optional: defaults to 200 if data or body is provided, 204 otherwise.
+ *
+ * @property {ResponseHeaders} [headers] - The response headers as a key-value object.
+ *   Optional: defaults to an empty object if not provided.
+ *
+ * @property {any} [body] - The raw response body as a string or object.
+ *   Optional: if not provided, body is automatically populated from data using JSON.stringify.
+ *
+ * @property {T} [data] - The parsed JSON data to include in the response.
+ *   Optional: contains the response payload when JSON data is provided.
+ *
+ * @remarks
+ * - All properties are optional
+ * - At least one of data or body should be provided for meaningful responses
+ * - The Response class automatically defaults status to 200 or 204 based on content
+ * - If data is provided without body, body is automatically JSON.stringify(data)
+ * - Used by Response constructor and mock handlers
+ *
+ * @see Response for the class that uses these properties
+ * @see ResponseErrorProps for error response properties
+ */
+type ResponseProps<T = any> = {
+  status?: number;
+  headers?: ResponseHeaders;
+  body?: any;
+  data?: T;
+};
+/**
+ * Wrapper class for HTTP responses from FaasJS functions.
+ *
+ * Provides a consistent interface for handling server responses with status code, headers,
+ * body, and parsed data. Automatically handles JSON serialization and status code defaults.
+ *
+ * @template T - The type of the data property for type-safe response handling
+ *
+ * @property {number} status - The HTTP status code of the response.
+ *   Defaults to 200 if data or body is provided, 204 if neither is present.
+ * @property {ResponseHeaders} headers - The response headers as a key-value object.
+ *   Empty object if no headers were provided.
+ * @property {any} body - The raw response body as a string or object.
+ *   If data is provided without body, body is automatically set to JSON.stringify(data).
+ * @property {T} [data] - The parsed JSON data from the response.
+ *   Optional property that contains the response payload when JSON is provided.
+ *
+ * @param {ResponseProps<T>} [props] - Response properties including status, headers, body, and data.
+ *   All properties are optional with sensible defaults.
+ *
+ * @remarks
+ * - status defaults to 200 if data or body is present, 204 otherwise
+ * - body is automatically populated from data if not explicitly provided
+ * - headers defaults to an empty object if not provided
+ * - Use generic type parameter T for type-safe data access
+ * - Commonly used as the return type from client.action() method
+ * - Can be used in mock handlers to return structured responses
+ * - The data property is optional and may be undefined for responses without data
+ *
+ * @example Create successful response with data
+ * ```ts
+ * const response = new Response({
+ *   status: 200,
+ *   data: {
+ *     id: 123,
+ *     name: 'John Doe'
  *   }
+ * })
+ * console.log(response.status) // 200
+ * console.log(response.data.name) // 'John Doe'
+ * ```
+ *
+ * @example Create response with type safety
+ * ```ts
+ * interface User {
+ *   id: number
+ *   name: string
+ *   email: string
  * }
+ *
+ * const response = new Response<User>({
+ *   data: {
+ *     id: 123,
+ *     name: 'John',
+ *     email: 'john@example.com'
+ *   }
+ * })
+ * // TypeScript knows response.data.name is a string
+ * ```
+ *
+ * @example Create response with headers
+ * ```ts
+ * const response = new Response({
+ *   status: 201,
+ *   data: { created: true },
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *     'X-Request-Id': 'req-123',
+ *     'X-Cache-Key': 'user-123'
+ *   }
+ * })
+ * ```
+ *
+ * @example Create response with custom body
+ * ```ts
+ * const response = new Response({
+ *   status: 200,
+ *   body: JSON.stringify({ custom: 'format' }),
+ *   headers: { 'Content-Type': 'application/json' }
+ * })
+ * ```
+ *
+ * @example Create empty response (204 No Content)
+ * ```ts
+ * const response = new Response()
+ * // status: 204, headers: {}, body: undefined, data: undefined
  * ```
+ *
+ * @example Create error response
+ * ```ts
+ * const response = new Response({
+ *   status: 404,
+ *   data: {
+ *     error: {
+ *       message: 'User not found',
+ *       code: 'USER_NOT_FOUND'
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example Use in mock handler
+ * ```ts
+ * setMock(async (action, params) => {
+ *   if (action === 'user') {
+ *     return new Response({
+ *       status: 200,
+ *       data: { id: params.id, name: 'Mock User' }
+ *     })
+ *   }
+ *   return new Response({ status: 404, data: { error: 'Not found' } })
+ * })
+ * ```
+ *
+ * @see ResponseProps for response property type
+ * @see ResponseError for error response handling
+ * @see FaasBrowserClient.action for method returning Response
  */
-interface FaasActions {
-  /**
-   * Internal placeholder to keep this interface visible in generated docs.
-   */
-  faasjsActionsPlaceholder?: {
-    Params: Record<string, any>;
-    Data: Record<string, any>;
-  };
+declare class Response<T = any> {
+  readonly status: number;
+  readonly headers: ResponseHeaders;
+  readonly body: any;
+  readonly data?: T;
+  constructor(props?: ResponseProps<T>);
 }
+type ResponseErrorProps = {
+  message: string; /** @default 500 */
+  status?: number; /** @default {} */
+  headers?: ResponseHeaders; /** @default { error: Error(message) } */
+  body?: any;
+  originalError?: Error;
+};
 /**
- * Infer all action paths declared in {@link FaasActions}.
- */
-type FaasActionPaths = Exclude<Extract<keyof FaasActions, string>, 'faasjsActionsPlaceholder'>;
-/**
- * Union type accepted by action helpers.
+ * Custom error class for handling HTTP response errors from FaasJS requests.
+ *
+ * Extends the built-in Error class to provide additional information about failed requests,
+ * including HTTP status code, response headers, response body, and the original error.
+ *
+ * @class ResponseError
+ * @extends {Error}
+ *
+ * @property {number} status - The HTTP status code of the failed response. Defaults to 500 if not provided.
+ * @property {ResponseHeaders} headers - The response headers from the failed request.
+ * @property {any} body - The response body containing error details or the original error if available.
+ * @property {Error} [originalError] - The original Error object if this ResponseError was created from another Error.
+ *
+ * @param {string | Error | ResponseErrorProps} data - The error message, an Error object, or a ResponseErrorProps object.
+ * @param {Omit<ResponseErrorProps, 'message' | 'originalError'>} [options] - Additional options for the error (status, headers, body).
+ *
+ * @example Basic error with message
+ * ```ts
+ * throw new ResponseError('User not found')
+ * // or inside action method:
+ * catch (error) {
+ *   throw new ResponseError(error.message)
+ * }
+ * ```
+ *
+ * @example Error from existing Error
+ * ```ts
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   throw new ResponseError(error, {
+ *     status: 500,
+ *     headers: { 'X-Error-Type': 'internal' }
+ *   })
+ * }
+ * ```
+ *
+ * @example Error with complete response details
+ * ```ts
+ * throw new ResponseError({
+ *   message: 'Validation failed',
+ *   status: 400,
+ *   headers: { 'X-Error-Code': 'VALIDATION_ERROR' },
+ *   body: {
+ *     error: {
+ *       message: 'Validation failed',
+ *       fields: ['email', 'password']
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example Handling ResponseError in client
+ * ```ts
+ * try {
+ *   const response = await client.action('user', { id: 123 })
+ *   console.log(response.data)
+ * } catch (error) {
+ *   if (error instanceof ResponseError) {
+ *     console.error(`Request failed: ${error.message}`)
+ *     console.error(`Status: ${error.status}`)
+ *     if (error.body) {
+ *       console.error('Error details:', error.body)
+ *     }
+ *     if (error.headers['X-Request-Id']) {
+ *       console.error('Request ID:', error.headers['X-Request-Id'])
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Throwing ResponseError from mock
+ * ```ts
+ * setMock(async (action, params) => {
+ *   if (action === 'login') {
+ *     if (!params.email || !params.password) {
+ *       throw new ResponseError({
+ *         message: 'Email and password are required',
+ *         status: 400,
+ *         body: { error: 'missing_fields' }
+ *       })
+ *     }
+ *     return { data: { token: 'abc123' } }
+ *   }
+ * })
+ * ```
+ *
+ * @remarks
+ * - ResponseError is automatically thrown by the action method when the server returns an error (status >= 400)
+ * - The error message from server responses is extracted from body.error.message if available
+ * - When created from an Error object, the original error is preserved in the originalError property
+ * - The status property defaults to 500 if not explicitly provided
+ * - Use instanceof ResponseError to distinguish FaasJS errors from other JavaScript errors
+ * - The body property can contain structured error information from the server response
+ *
+ * @see FaasBrowserClient.action for how ResponseError is thrown in requests
+ * @see ResponseProps for the structure of response data
+ * @see setMock for mocking errors in tests
  */
-type FaasActionUnionType = FaasActionPaths | Record<string, any> | string;
+declare class ResponseError extends Error {
+  readonly status: number;
+  readonly headers: ResponseHeaders;
+  readonly body: any;
+  readonly originalError?: Error;
+  constructor(msg: string | Error, options?: Omit<ResponseErrorProps, 'message' | 'originalError'>);
+  constructor(props: ResponseErrorProps);
+}
 /**
- * Infer the action path type.
+ * Mock handler function type for testing FaasJS requests.
  *
- * Returns the original type when `T` is a known action path,
- * otherwise falls back to `string`.
+ * Defines the signature for functions that can mock API requests during testing.
+ * Mock handlers receive request parameters and return simulated responses or errors.
  *
- * @example
- * ```typescript
- * type A = FaasAction<'demo'> // 'demo'
- * type B = FaasAction<number> // string
+ * @param {string} action - The function path/action being requested (e.g., 'user', 'data/list').
+ *   Converted to lowercase by the client before being passed to the handler.
+ *
+ * @param {Record<string, any> | undefined} params - The parameters passed to the action.
+ *   May be undefined if the action was called without parameters.
+ *   Parameters are passed as a plain object (already JSON-serialized if needed).
+ *
+ * @param {Options} options - The full request options including headers, beforeRequest hook, and other config.
+ *   Includes X-FaasJS-Request-Id header in the headers object.
+ *   Contains merged client defaults and per-request options.
+ *
+ * @returns {Promise<ResponseProps> | Promise<void> | Promise<Error>} - A Promise resolving to:
+ *   - ResponseProps: Mock response data (status, headers, body, data)
+ *   - void: Returns an empty response (204 No Content)
+ *   - Error: Throws ResponseError when returning an Error object
+ *
+ * @remarks
+ * - Used by setMock() function to mock API calls during tests
+ * - Affects all FaasBrowserClient instances when set globally
+ * - Can return different responses based on action or params
+ * - Returning an Error object causes the action() method to reject with ResponseError
+ * - Async function - must return a Promise
+ * - Receives the fully merged options including default headers
+ *
+ * @example Basic mock returning data
+ * ```ts
+ * setMock(async (action, params, options) => {
+ *   if (action === 'user') {
+ *     return {
+ *       status: 200,
+ *       data: { id: params.id, name: 'Mock User' }
+ *     }
+ *   }
+ *   return { status: 404, data: { error: 'Not found' } }
+ * })
+ * ```
+ *
+ * @example Conditional mock based on parameters
+ * ```ts
+ * setMock(async (action, params) => {
+ *   if (action === 'login') {
+ *     if (params.email === 'admin@example.com' && params.password === 'admin') {
+ *       return { data: { token: 'admin-token', role: 'admin' } }
+ *     }
+ *     return { status: 401, data: { error: 'Invalid credentials' } }
+ *   }
+ * })
+ * ```
+ *
+ * @example Throwing error from mock
+ * ```ts
+ * setMock(async (action) => {
+ *   if (action === 'protected') {
+ *     return new Error('Unauthorized access')
+ *     // This will be wrapped in ResponseError and thrown
+ *   }
+ * })
  * ```
+ *
+ * @example Returning void for empty response
+ * ```ts
+ * setMock(async (action) => {
+ *   if (action === 'delete') {
+ *     // Return void for 204 No Content
+ *     return
+ *   }
+ *   return { data: { success: true } }
+ * })
+ * ```
+ *
+ * @see setMock for setting up mock handlers
+ * @see ResponseProps for response structure
+ * @see ResponseError for error handling
  */
-type FaasAction<T = any> = T extends FaasActionPaths ? T : string;
+type MockHandler = (action: string, params: Record<string, any> | undefined, options: Options) => Promise<ResponseProps> | Promise<void> | Promise<Error>;
 /**
- * Infer params type by action path.
+ * Set global mock handler for testing. Mock affects all FaasBrowserClient instances.
  *
- * @example
- * ```typescript
- * type DemoParams = FaasParams<'demo'>
+ * @param handler - Mock handler, can be:
+ *   - MockHandler function: receives (action, params, options) and returns response data
+ *   - ResponseProps object: static response data
+ *   - Response instance: pre-configured Response object
+ *   - null or undefined: clear mock
+ *
+ * @example Use MockHandler function
+ * ```ts
+ * setMock(async (action, params, options) => {
+ *   if (action === 'user') {
+ *     return { data: { name: 'John' } }
+ *   }
+ *   return { status: 404, data: { error: 'Not found' } }
+ * })
+ *
+ * const response = await client.action('user')
+ * ```
+ *
+ * @example Use ResponseProps object
+ * ```ts
+ * setMock({
+ *   status: 200,
+ *   data: { result: 'success' },
+ *   headers: { 'X-Custom': 'value' }
+ * })
+ * ```
+ *
+ * @example Use Response instance
+ * ```ts
+ * setMock(new Response({
+ *   status: 200,
+ *   data: { result: 'success' }
+ * }))
+ * ```
+ *
+ * @example Clear mock
+ * ```ts
+ * setMock(null)
+ * // or
+ * setMock(undefined)
+ * ```
+ *
+ * @example Handle errors
+ * ```ts
+ * setMock(async () => {
+ *   throw new Error('Internal error')
+ * })
+ * // This will reject with ResponseError
  * ```
  */
-type FaasParams<T = any> = T extends FaasActionPaths ? FaasActions[T]['Params'] : Record<string, any>;
+declare function setMock(handler: MockHandler | ResponseProps | Response | null): void;
 /**
- * Infer response data type by action path.
+ * Browser client for FaasJS - provides HTTP client functionality for making API requests from web applications.
  *
- * If `T` is already a plain object type, it is returned directly.
+ * @template PathOrData - Type parameter extending FaasActionUnionType for type-safe requests
  *
- * @example
- * ```typescript
- * type DemoData = FaasData<'demo'>
- * type CustomData = FaasData<{ value: number }> // { value: number }
+ * Features:
+ * - Type-safe API requests with TypeScript support
+ * - Built-in mock support for testing
+ * - Custom request function support
+ * - Request/response hooks (beforeRequest)
+ * - Automatic error handling with ResponseError
+ * - Streaming support for large responses
+ * - Multiple instance support with unique IDs
+ *
+ * @remarks
+ * - All requests are POST requests by default
+ * - Automatically adds X-FaasJS-Request-Id header for request tracking
+ * - baseUrl must end with '/' (will throw Error if not)
+ * - Supports global mock via setMock() for testing all instances
+ *
+ * @example Basic usage
+ * ```ts
+ * import { FaasBrowserClient } from '@faasjs/react'
+ *
+ * const client = new FaasBrowserClient('http://localhost:8080/')
+ * const response = await client.action('func', { key: 'value' })
+ * console.log(response.data)
  * ```
+ *
+ * @example With custom headers and options
+ * ```ts
+ * const client = new FaasBrowserClient('https://api.example.com/', {
+ *   headers: { 'X-API-Key': 'secret' },
+ *   beforeRequest: async ({ action, params, headers }) => {
+ *     console.log(`Calling ${action} with params:`, params)
+ *   }
+ * })
+ * ```
+ *
+ * @example Multiple instances
+ * ```ts
+ * const apiClient = new FaasBrowserClient('https://api.example.com/')
+ * const localClient = new FaasBrowserClient('http://localhost:3000/')
+ *
+ * const apiData = await apiClient.action('users')
+ * const localData = await localClient.action('data')
+ * ```
+ *
+ * @example Error handling
+ * ```ts
+ * const client = new FaasBrowserClient('https://api.example.com/')
+ *
+ * try {
+ *   const response = await client.action('user', { id: 123 })
+ *   console.log(response.data)
+ * } catch (error) {
+ *   if (error instanceof ResponseError) {
+ *     console.error(`Request failed: ${error.message}`, error.status)
+ *   } else {
+ *     console.error('Unexpected error:', error)
+ *   }
+ * }
+ * ```
+ *
+ * @throws {Error} When baseUrl does not end with '/'
+ *
+ * @see setMock for testing support
+ * @see ResponseError for error handling
  */
-type FaasData<T = any> = T extends FaasActionPaths ? FaasActions[T]['Data'] : T extends Record<string, any> ? T : Record<string, any>;
+declare class FaasBrowserClient {
+  readonly id: string;
+  baseUrl: BaseUrl;
+  defaultOptions: Options;
+  /**
+   * Creates a new FaasBrowserClient instance.
+   *
+   * @param baseUrl - Base URL for all API requests. Must end with '/'. Defaults to '/' for relative requests.
+   *   @throws {Error} If baseUrl does not end with '/'
+   * @param options - Configuration options for the client.
+   *   Supports default headers, beforeRequest hook, custom request function,
+   *   baseUrl override, and streaming mode.
+   *
+   * @example Basic initialization
+   * ```ts
+   * const client = new FaasBrowserClient('/')
+   * ```
+   *
+   * @example With API endpoint
+   * ```ts
+   * const client = new FaasBrowserClient('https://api.example.com/')
+   * ```
+   *
+   * @example With custom headers
+   * ```ts
+   * const client = new FaasBrowserClient('https://api.example.com/', {
+   *   headers: {
+   *     'Authorization': 'Bearer token123',
+   *     'X-Custom-Header': 'value'
+   *   }
+   * })
+   * ```
+   *
+   * @example With beforeRequest hook
+   * ```ts
+   * const client = new FaasBrowserClient('https://api.example.com/', {
+   *   beforeRequest: async ({ action, params, headers }) => {
+   *     console.log(`Requesting ${action}`, params)
+   *     // Modify headers before request
+   *     headers['X-Timestamp'] = Date.now().toString()
+   *   }
+   * })
+   * ```
+   *
+   * @example With custom request function
+   * ```ts
+   * import axios from 'axios'
+   *
+   * const client = new FaasBrowserClient('/', {
+   *   request: async (url, options) => {
+   *     const response = await axios.post(url, options.body, {
+   *       headers: options.headers
+   *     })
+   *     return new Response({
+   *       status: response.status,
+   *       headers: response.headers,
+   *       data: response.data
+   *     })
+   *   }
+   * })
+   * ```
+   *
+   * @throws {Error} When baseUrl does not end with '/'
+   */
+  constructor(baseUrl?: BaseUrl, options?: Options);
+  /**
+   * Makes a request to a FaasJS function.
+   *
+   * @template PathOrData - The function path or data type for type safety
+   * @param action - The function path to call. Converted to lowercase when constructing the URL.
+   *   Must be a non-empty string.
+   * @param params - The parameters to send to the function. Will be serialized as JSON.
+   *   Optional if the function accepts no parameters.
+   * @param options - Optional request options that override client defaults.
+   *   Supports headers, beforeRequest hook, custom request function, baseUrl override, and streaming mode.
+   *
+   * @returns A Promise that resolves to a Response object containing status, headers, body, and data.
+   *   The data property is typed based on the PathOrData generic parameter.
+   *
+   * @throws {Error} When action is not provided or is empty
+   * @throws {ResponseError} When the server returns an error response (status >= 400 or body.error exists)
+   * @throws {NetworkError} When network request fails
+   *
+   * @remarks
+   * - All requests are POST requests by default
+   * - Action path is automatically converted to lowercase
+   * - A unique request ID is generated for each request and sent in X-FaasJS-Request-Id header
+   * - Headers are merged from client defaults and request options (request options take precedence)
+   * - If a global mock is set via setMock(), it will be used instead of making real requests
+   * - If a custom request function is provided in options, it will be used instead of fetch
+   * - When stream option is true, returns the native fetch Response instead of a wrapped Response
+   * - Response body is automatically parsed as JSON when possible
+   * - Server errors (body.error) are automatically converted to ResponseError
+   *
+   * @example Basic request
+   * ```ts
+   * const response = await client.action('user', { id: 123 })
+   * console.log(response.data)
+   * ```
+   *
+   * @example With no parameters
+   * ```ts
+   * const response = await client.action('status')
+   * console.log(response.data.status)
+   * ```
+   *
+   * @example With custom options
+   * ```ts
+   * const response = await client.action('data', {
+   *   limit: 10,
+   *   offset: 0
+   * }, {
+   *   headers: { 'X-Custom-Header': 'value' }
+   * })
+   * ```
+   *
+   * @example Streaming large response
+   * ```ts
+   * const response = await client.action('stream', {
+   *   format: 'json'
+   * }, {
+   *   stream: true
+   * })
+   * // response is native fetch Response with streaming support
+   * const reader = response.body.getReader()
+   * ```
+   *
+   * @example With type safety
+   * ```ts
+   * interface UserData {
+   *   id: number
+   *   name: string
+   *   email: string
+   * }
+   *
+   * const response = await client.action<{
+   *   action: 'user'
+   *   params: { id: number }
+   *   data: UserData
+   * }>('user', { id: 123 })
+   * console.log(response.data.name) // TypeScript knows it's a string
+   * ```
+   *
+   * @example Handling errors
+   * ```ts
+   * try {
+   *   const response = await client.action('user', { id: 123 })
+   *   console.log(response.data)
+   * } catch (error) {
+   *   if (error instanceof ResponseError) {
+   *     console.error(`Server error: ${error.message}`, error.status)
+   *     if (error.data) console.error('Error details:', error.data)
+   *   } else {
+   *     console.error('Network error:', error)
+   *   }
+   * }
+   * ```
+   *
+   * @example Chaining requests
+   * ```ts
+   * const userId = await client.action('createUser', {
+   *   name: 'John',
+   *   email: 'john@example.com'
+   * })
+   *
+   * const profile = await client.action('getProfile', {
+   *   userId: userId.data.id
+   * })
+   * ```
+   */
+  action<PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params?: FaasParams$1<PathOrData>, options?: Options): Promise<Response<FaasData$1<PathOrData>>>;
+}
 //#endregion
 //#region src/FaasDataWrapper.d.ts
 /**
  * Injects FaasData props.
  */
-type FaasDataInjection<PathOrData extends FaasActionUnionType = any> = {
-  action: FaasAction<PathOrData>;
-  params: FaasParams<PathOrData>;
+type FaasDataInjection<PathOrData extends FaasActionUnionType$1 = any> = {
+  action: FaasAction$1<PathOrData>;
+  params: FaasParams$1<PathOrData>;
   loading: boolean;
   reloadTimes: number;
-  data: FaasData<PathOrData>;
+  data: FaasData$1<PathOrData>;
   error: any;
-  promise: Promise<Response$1<FaasData<PathOrData>>>;
+  promise: Promise<Response<FaasData$1<PathOrData>>>;
   /**
    * Reloads data with new or existing parameters.
    *
    * **Note**: It will sets skip to false before loading data.
    */
-  reload(params?: Record<string, any>): Promise<FaasData<PathOrData>>;
-  setData: React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>;
+  reload(params?: Record<string, any>): Promise<FaasData$1<PathOrData>>;
+  setData: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>;
   setLoading: React.Dispatch<React.SetStateAction<boolean>>;
-  setPromise: React.Dispatch<React.SetStateAction<Promise<Response$1<FaasData<PathOrData>>>>>;
+  setPromise: React.Dispatch<React.SetStateAction<Promise<Response<FaasData$1<PathOrData>>>>>;
   setError: React.Dispatch<React.SetStateAction<any>>;
 };
-type FaasDataWrapperProps<PathOrData extends FaasActionUnionType> = {
+type FaasDataWrapperProps<PathOrData extends FaasActionUnionType$1> = {
   render?(args: FaasDataInjection<PathOrData>): JSX.Element | JSX.Element[];
   children?: React.ReactElement<Partial<FaasDataInjection<PathOrData>>>;
   fallback?: JSX.Element | false;
-  action: FaasAction<PathOrData>;
-  params?: FaasParams<PathOrData>;
+  action: FaasAction$1<PathOrData>;
+  params?: FaasParams$1<PathOrData>;
   onDataChange?(args: FaasDataInjection<PathOrData>): void; /** use custom data, should work with setData */
-  data?: FaasData<PathOrData>; /** use custom setData, should work with data */
-  setData?: React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>;
+  data?: FaasData$1<PathOrData>; /** use custom setData, should work with data */
+  setData?: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>;
   baseUrl?: BaseUrl;
   ref?: React.Ref<FaasDataWrapperRef<PathOrData>>;
 };
-type FaasDataWrapperRef<PathOrData extends FaasActionUnionType = any> = FaasDataInjection<PathOrData>;
-declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType = any>(props: FaasDataWrapperProps<PathOrData> & react.RefAttributes<FaasDataWrapperRef<PathOrData>>) => React.ReactElement | null;
+type FaasDataWrapperRef<PathOrData extends FaasActionUnionType$1 = any> = FaasDataInjection<PathOrData>;
+declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType$1 = any>(props: FaasDataWrapperProps<PathOrData> & react.RefAttributes<FaasDataWrapperRef<PathOrData>>) => React.ReactElement | null;
 /**
  * HOC to wrap a component with FaasDataWrapper
  *
@@ -120,7 +841,7 @@ declare const FaasDataWrapper: <PathOrData extends FaasActionUnionType = any>(pr
  * const MyComponent = withFaasData(({ data }) => <div>{data.name}</div>, { action: 'test', params: { a: 1 } })
  * ```
  */
-declare function withFaasData<PathOrData extends FaasActionUnionType, TComponentProps extends Required<FaasDataInjection<PathOrData>> = Required<FaasDataInjection<PathOrData>>>(Component: React.FC<TComponentProps>, faasProps: FaasDataWrapperProps<PathOrData>): React.FC<Omit<TComponentProps, keyof FaasDataInjection<PathOrData>> & Record<string, any>>;
+declare function withFaasData<PathOrData extends FaasActionUnionType$1, TComponentProps extends Required<FaasDataInjection<PathOrData>> = Required<FaasDataInjection<PathOrData>>>(Component: React.FC<TComponentProps>, faasProps: FaasDataWrapperProps<PathOrData>): React.FC<Omit<TComponentProps, keyof FaasDataInjection<PathOrData>> & Record<string, any>>;
 //#endregion
 //#region src/faas.d.ts
 /**
@@ -137,19 +858,19 @@ declare function withFaasData<PathOrData extends FaasActionUnionType, TComponent
  * })
  * ```
  */
-declare function faas<PathOrData extends FaasActionUnionType>(action: FaasAction<PathOrData>, params: FaasParams<PathOrData>, options?: Options$1): Promise<Response$1<FaasData<PathOrData>>>;
+declare function faas<PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, params: FaasParams$1<PathOrData>, options?: Options): Promise<Response<FaasData$1<PathOrData>>>;
 //#endregion
 //#region src/useFaas.d.ts
-type useFaasOptions<PathOrData extends FaasActionUnionType> = {
-  params?: FaasParams<PathOrData>;
-  data?: FaasData<PathOrData>;
-  setData?: React.Dispatch<React.SetStateAction<FaasData<PathOrData>>>;
+type useFaasOptions<PathOrData extends FaasActionUnionType$1> = {
+  params?: FaasParams$1<PathOrData>;
+  data?: FaasData$1<PathOrData>;
+  setData?: React.Dispatch<React.SetStateAction<FaasData$1<PathOrData>>>;
   /**
    * If skip is true, the request will not be sent.
    *
    * However, you can still use reload to send the request.
    */
-  skip?: boolean | ((params: FaasParams<PathOrData>) => boolean); /** Send the last request after milliseconds */
+  skip?: boolean | ((params: FaasParams$1<PathOrData>) => boolean); /** Send the last request after milliseconds */
   debounce?: number;
   baseUrl?: BaseUrl;
 };
@@ -168,13 +889,13 @@ type useFaasOptions<PathOrData extends FaasActionUnionType> = {
  * }
  * ```
  */
-declare function useFaas<PathOrData extends FaasActionUnionType>(action: FaasAction<PathOrData>, defaultParams: FaasParams<PathOrData>, options?: useFaasOptions<PathOrData>): FaasDataInjection<PathOrData>;
+declare function useFaas<PathOrData extends FaasActionUnionType$1>(action: FaasAction$1<PathOrData>, defaultParams: FaasParams$1<PathOrData>, options?: useFaasOptions<PathOrData>): FaasDataInjection<PathOrData>;
 //#endregion
 //#region src/client.d.ts
-type OnError = (action: string, params: Record<string, any>) => (res: ResponseError$1) => Promise<void>;
+type OnError = (action: string, params: Record<string, any>) => (res: ResponseError) => Promise<void>;
 type FaasReactClientOptions = {
   /** @default `/` */baseUrl?: BaseUrl;
-  options?: Options$1;
+  options?: Options;
   /**
    * @example
    * ```ts
@@ -250,7 +971,7 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, {
   static displayName: string;
   constructor(props: ErrorBoundaryProps);
   componentDidCatch(error: Error, info: ErrorInfo): void;
-  render(): string | number | bigint | boolean | react_jsx_runtime0.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
+  render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime0.JSX.Element | null;
 }
 //#endregion
 //#region src/equal.d.ts
@@ -547,7 +1268,7 @@ declare function OptionalWrapper({
   Wrapper,
   wrapperProps,
   children
-}: OptionalWrapperProps): string | number | bigint | boolean | react_jsx_runtime0.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
+}: OptionalWrapperProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime0.JSX.Element | null | undefined;
 declare namespace OptionalWrapper {
   var displayName: string;
 }
@@ -766,4 +1487,4 @@ declare function usePrevious<T = any>(value: T): T | undefined;
  */
 declare function useStateRef<T = any>(initialValue?: T): [T | null, Dispatch<SetStateAction<T | null>>, RefObject<T | null>];
 //#endregion
-export { ErrorBoundary, ErrorBoundaryProps, ErrorChildrenProps, type FaasAction, type FaasActionUnionType, type FaasData, FaasDataInjection, FaasDataWrapper, FaasDataWrapperProps, FaasDataWrapperRef, type FaasParams, FaasReactClient, FaasReactClientInstance, FaasReactClientOptions, FormContainer as Form, type FormButtonElementProps, FormContextProps, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormDefaultRulesOptions, FormElementTypes, FormInput, type FormInputElementProps, FormInputProps, FormItem, FormItemName, FormItemProps, type FormLabelElementProps, FormLang, type FormProps, FormRule, FormRules, InferFormInputProps, InferFormRulesOptions, InferRuleOption, OnError, OptionalWrapper, OptionalWrapperProps, type Options, type Response, type ResponseError, type ResponseHeaders, StateSetters, StatesWithSetters, UseFaasStreamOptions, UseFaasStreamResult, createSplittingContext, equal, faas, getClient, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasOptions, useFaasStream, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };
+export { BaseUrl, ErrorBoundary, ErrorBoundaryProps, ErrorChildrenProps, type FaasAction, type FaasActionUnionType, FaasBrowserClient, FaasBrowserClientAction, type FaasData, FaasDataInjection, FaasDataWrapper, FaasDataWrapperProps, FaasDataWrapperRef, type FaasParams, FaasReactClient, FaasReactClientInstance, FaasReactClientOptions, FormContainer as Form, type FormButtonElementProps, FormContextProps, FormContextProvider, FormDefaultElements, FormDefaultLang, FormDefaultRules, FormDefaultRulesOptions, FormElementTypes, FormInput, type FormInputElementProps, FormInputProps, FormItem, FormItemName, FormItemProps, type FormLabelElementProps, FormLang, type FormProps, FormRule, FormRules, InferFormInputProps, InferFormRulesOptions, InferRuleOption, MockHandler, OnError, OptionalWrapper, OptionalWrapperProps, Options, Response, ResponseError, ResponseErrorProps, ResponseHeaders, ResponseProps, StateSetters, StatesWithSetters, UseFaasStreamOptions, UseFaasStreamResult, createSplittingContext, equal, faas, generateId, getClient, setMock, useConstant, useEqualCallback, useEqualEffect, useEqualMemo, useEqualMemoize, useFaas, useFaasOptions, useFaasStream, useFormContext, usePrevious, useSplittingState, useStateRef, validValues, withFaasData };