@openstage/monadyssey-fetch 3.0.0-beta.1

package/dist/monadyssey-fetch.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@openstage/monadyssey-core`);var t=e=>typeof e!=`object`||!e||e instanceof FormData||e instanceof Blob||e instanceof ArrayBuffer||e instanceof URLSearchParams||typeof ReadableStream<`u`&&e instanceof ReadableStream||ArrayBuffer.isView(e),n=e=>{let t={};for(let[n,r]of Object.entries(e))r!==void 0&&(t[n.toLowerCase()]=r);return t},r=(e,t,n)=>{let r=n;for(let t of[...e].reverse()){let e=r;r=n=>t.intercept(n,e)}return r(t)},i=async(e,t,n)=>{if(e.status===204||e.status===205)return null;try{switch(t){case`json`:return await e.json();case`text`:return await e.text();case`blob`:return await e.blob();case`arrayBuffer`:return await e.arrayBuffer();case`formData`:return await e.formData();default:throw a(`Unsupported response type: ${t}`,n,e)}}catch(t){throw t instanceof c?t:a(t,n,e)}},a=(e,t,n)=>{let r=o(n),i=n?n.body:null,a=e instanceof Error?e.message:typeof e==`string`?e:typeof e==`object`&&e&&`message`in e?String(e.message):`An unknown error occurred.`;return new c(n?.status||500,a,i,t,r)},o=e=>{if(!e)return{};try{return Object.fromEntries(e.headers.entries())}catch{return{}}},s=class{interceptors;baseUrl;defaultHeaders;defaultTimeout;defaultCredentials;constructor(e={}){this.interceptors=Object.freeze([...e.interceptors??[]]),this.baseUrl=e.baseUrl,this.defaultHeaders=e.defaultHeaders??{},this.defaultTimeout=e.timeout,this.defaultCredentials=e.credentials??`same-origin`}get(e,t){return this.request(e,`GET`,t)}post(e,t,n){return this.request(e,`POST`,{...n,body:t})}put(e,t,n){return this.request(e,`PUT`,{...n,body:t})}patch(e,t,n){return this.request(e,`PATCH`,{...n,body:t})}delete(e,t){return this.request(e,`DELETE`,t)}fetch(e,t,n={}){return this.request(e,t,n)}resolveUrl(e){if(!this.baseUrl)return e;try{return new URL(e),e}catch{return`${this.baseUrl.endsWith(`/`)?this.baseUrl.slice(0,-1):this.baseUrl}${e.startsWith(`/`)?e:`/${e}`}`}}request(s,l,u={}){let d=this.resolveUrl(s),f=u.timeout??this.defaultTimeout;return e.IO.cancellable(async e=>{let{headers:a={},body:s,responseType:p=`json`,credentials:m=this.defaultCredentials,observe:h=`body`,transform:g=e=>e}=u,_=n({...this.defaultHeaders,...a});typeof s==`object`&&s&&!t(s)&&!(`content-type`in _)&&(_[`content-type`]=`application/json`),s instanceof FormData&&delete _[`content-type`];let v=l===`GET`||l===`HEAD`||s==null?void 0:t(s)?s:_[`content-type`]===`application/json`?JSON.stringify(s):s,y,b,x=f==null?e:(y=new AbortController,e.addEventListener(`abort`,()=>y.abort(e.reason),{once:!0}),b=setTimeout(()=>y.abort(new DOMException(`Request timed out`,`TimeoutError`)),f),y.signal);try{let e={method:l,headers:_,credentials:m,body:v,signal:x},t=await r(this.interceptors,e,e=>fetch(d,e));if(!t.ok){let e=await i(t,p,d),n=o(t);throw new c(t.status,t.statusText,e,d,n)}return h===`response`?t:g(await i(t,p,d))}finally{b!=null&&clearTimeout(b)}},e=>e instanceof c?e:a(e,d))}},c=class extends Error{status;rawMessage;body;url;headers;constructor(e,t,n,r,i){super(`Request to '${r}' failed with status ${e} and message: ${t}.`),this.name=`HttpError`,this.status=e,this.rawMessage=t,this.body=n,this.url=r,this.headers=i}};exports.HttpClient=s,exports.HttpError=c;
+//# sourceMappingURL=monadyssey-fetch.cjs.map

package/dist/monadyssey-fetch.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"monadyssey-fetch.cjs","names":[],"sources":["../src/http-client.ts"],"sourcesContent":["import { IO } from \"@openstage/monadyssey-core\";\nimport { Credentials, HttpClientConfig, HttpInterceptor, Method, Options, ResponseType } from \"./options\";\n\n/**\n * Returns `true` if the body is a type that the fetch API knows how to send natively.\n * These types must NOT be JSON.stringified and must NOT have a Content-Type header auto-set\n * (the browser handles multipart boundaries for FormData, etc.).\n */\nconst isNativeBody = (body: unknown): boolean =>\n  typeof body !== \"object\" ||\n  body === null ||\n  body instanceof FormData ||\n  body instanceof Blob ||\n  body instanceof ArrayBuffer ||\n  body instanceof URLSearchParams ||\n  (typeof ReadableStream !== \"undefined\" && body instanceof ReadableStream) ||\n  ArrayBuffer.isView(body);\n\n/**\n * Normalizes header keys to lowercase for case-insensitive comparison.\n * HTTP header names are case-insensitive per RFC 7230.\n */\nconst normalizeHeaders = (headers: Record<string, string>): Record<string, string> => {\n  const result: Record<string, string> = {};\n  for (const [key, value] of Object.entries(headers)) {\n    if (value !== undefined) {\n      result[key.toLowerCase()] = value;\n    }\n  }\n  return result;\n};\n\n/**\n * Builds the interceptor chain as a pure function. No global state.\n * Interceptors are applied in registration order — first registered is outermost.\n */\nconst runInterceptors = (\n  interceptors: readonly HttpInterceptor[],\n  req: RequestInit,\n  fn: (req: RequestInit) => Promise<Response>\n): Promise<Response> => {\n  let next = fn;\n  for (const interceptor of [...interceptors].reverse()) {\n    const currentNext = next;\n    next = (r: RequestInit) => interceptor.intercept(r, currentNext);\n  }\n  return next(req);\n};\n\nconst parseBody = async (response: Response, responseType: ResponseType, url: string): Promise<unknown> => {\n  if (response.status === 204 || response.status === 205) {\n    return null;\n  }\n  try {\n    switch (responseType) {\n      case \"json\":\n        return await response.json();\n      case \"text\":\n        return await response.text();\n      case \"blob\":\n        return await response.blob();\n      case \"arrayBuffer\":\n        return await response.arrayBuffer();\n      case \"formData\":\n        return await response.formData();\n      default:\n        throw toHttpError(`Unsupported response type: ${responseType}`, url, response);\n    }\n  } catch (e: unknown) {\n    if (e instanceof HttpError) throw e;\n    throw toHttpError(e, url, response);\n  }\n};\n\nconst toHttpError = (e: unknown, uri: string, response?: Response): HttpError => {\n  const headers = extractHeadersFrom(response);\n  const body = response ? response.body : null;\n\n  const message =\n    e instanceof Error\n      ? e.message\n      : typeof e === \"string\"\n        ? e\n        : typeof e === \"object\" && e !== null && \"message\" in e\n          ? String((e as any).message)\n          : \"An unknown error occurred.\";\n\n  return new HttpError(response?.status || 500, message, body, uri, headers);\n};\n\nconst extractHeadersFrom = (response?: Response): Record<string, string> => {\n  if (!response) return {};\n  try {\n    return Object.fromEntries(response.headers.entries());\n  } catch {\n    return {};\n  }\n};\n\n/**\n * A composable HTTP client that wraps the native `fetch` API, returning `IO` instances instead of Promises.\n *\n * Unlike v1, `HttpClient` is instantiable — each instance carries its own configuration (base URL,\n * interceptors, default headers, timeout, credentials). This allows different parts of an application\n * to use independently configured clients.\n *\n * All HTTP methods return `IO<HttpError, A | null>`, enabling lazy execution, functional composition,\n * and explicit error handling. Cancellation is supported: when an IO is cancelled (via fiber or\n * timeout), the underlying `fetch` call is aborted through `AbortSignal`.\n *\n * **On the `| null` in the return type:** when the server responds with `204 No Content` or\n * `205 Reset Content`, there is no body to parse and the IO succeeds with `null`. This is a\n * protocol-level fact (the HTTP spec says these statuses have no body), distinct from a\n * domain-level optionality. For that reason the methods return `IO<HttpError, A | null>` rather\n * than `IO<HttpError, Option<A>>`. `Option` is the right tool when a value might be absent at\n * the domain level; `| null` is honest when the absence is structural to the protocol. For the\n * 95% case where you control the endpoint and never receive 204, the `| null` is a brief\n * `?? defaultValue` away.\n *\n * **Default credentials:** `same-origin`, matching the platform `fetch` default. Set\n * `credentials: \"include\"` explicitly per-client or per-request if you need cookies to flow\n * cross-origin.\n *\n * @example\n * const api = new HttpClient({\n *   baseUrl: \"https://api.example.com\",\n *   interceptors: [authInterceptor],\n *   defaultHeaders: { \"Accept\": \"application/json\" },\n *   timeout: 5000,\n * });\n *\n * const users = api.get<User[]>(\"/users\");\n */\nexport class HttpClient {\n  private readonly interceptors: readonly HttpInterceptor[];\n  private readonly baseUrl: string | undefined;\n  private readonly defaultHeaders: Record<string, string>;\n  private readonly defaultTimeout: number | undefined;\n  private readonly defaultCredentials: Credentials;\n\n  /**\n   * Creates a new HttpClient with the given configuration.\n   *\n   * @param {HttpClientConfig} config - Configuration for the client.\n   */\n  constructor(config: HttpClientConfig = {}) {\n    this.interceptors = Object.freeze([...(config.interceptors ?? [])]);\n    this.baseUrl = config.baseUrl;\n    this.defaultHeaders = config.defaultHeaders ?? {};\n    this.defaultTimeout = config.timeout;\n    this.defaultCredentials = config.credentials ?? \"same-origin\";\n  }\n\n  /**\n   * Performs a GET request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Omit<Options<A>, \"body\">} [options] - Request options (excluding body).\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  get(uri: string, options: Omit<Options, \"body\"> & { observe: \"response\" }): IO<HttpError, Response>;\n  get<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, A | null>;\n  get<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"GET\", options);\n  }\n\n  /**\n   * Performs a POST request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  post(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  post<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  post<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"POST\", { ...options, body });\n  }\n\n  /**\n   * Performs a PUT request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  put(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  put<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  put<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"PUT\", { ...options, body });\n  }\n\n  /**\n   * Performs a PATCH request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  patch(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  patch<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  patch<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"PATCH\", { ...options, body });\n  }\n\n  /**\n   * Performs a DELETE request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Omit<Options<A>, \"body\">} [options] - Request options (excluding body).\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  delete(uri: string, options: Omit<Options, \"body\"> & { observe: \"response\" }): IO<HttpError, Response>;\n  delete<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, A | null>;\n  delete<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"DELETE\", options);\n  }\n\n  /**\n   * Performs a custom HTTP request with the specified method.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Method} method - The HTTP method.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  fetch(uri: string, method: Method, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  fetch<A = any>(uri: string, method: Method, options?: Options<A>): IO<HttpError, A | null>;\n  fetch<A = any>(uri: string, method: Method, options: Options<A> = {}): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, method, options);\n  }\n\n  private resolveUrl(uri: string): string {\n    if (!this.baseUrl) return uri;\n    try {\n      new URL(uri);\n      return uri;\n    } catch {\n      const base = this.baseUrl.endsWith(\"/\") ? this.baseUrl.slice(0, -1) : this.baseUrl;\n      const path = uri.startsWith(\"/\") ? uri : `/${uri}`;\n      return `${base}${path}`;\n    }\n  }\n\n  private request<A = any>(uri: string, method: Method, options: Options<A> = {}): IO<HttpError, Response | A | null> {\n    const resolvedUrl = this.resolveUrl(uri);\n    const timeout = options.timeout ?? this.defaultTimeout;\n\n    return IO.cancellable<HttpError, Response | A | null>(\n      async (signal: AbortSignal) => {\n        const {\n          headers = {},\n          body,\n          responseType = \"json\",\n          credentials = this.defaultCredentials,\n          observe = \"body\",\n          transform = (data: unknown) => data as A,\n        } = options;\n\n        // Merge default headers + per-request headers, all lowercased\n        const mergedHeaders = normalizeHeaders({ ...this.defaultHeaders, ...headers });\n\n        // Auto-detect Content-Type only for plain objects (not FormData, Blob, etc.)\n        const shouldAutoJson =\n          body != null && typeof body === \"object\" && !isNativeBody(body) && !(\"content-type\" in mergedHeaders);\n\n        if (shouldAutoJson) {\n          mergedHeaders[\"content-type\"] = \"application/json\";\n        }\n\n        // For FormData, do NOT set Content-Type — the browser sets the multipart boundary\n        if (body instanceof FormData) {\n          delete mergedHeaders[\"content-type\"];\n        }\n\n        // Serialize body\n        const serializedBody =\n          method === \"GET\" || method === \"HEAD\" || body == null\n            ? undefined\n            : isNativeBody(body)\n              ? body\n              : mergedHeaders[\"content-type\"] === \"application/json\"\n                ? JSON.stringify(body)\n                : body;\n\n        // Timeout support: create a child controller that aborts on timeout or parent signal\n        let controller: AbortController | undefined;\n        let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n        const fetchSignal = (() => {\n          if (timeout != null) {\n            controller = new AbortController();\n            const onParentAbort = () => controller!.abort(signal.reason);\n            signal.addEventListener(\"abort\", onParentAbort, { once: true });\n            timeoutId = setTimeout(\n              () => controller!.abort(new DOMException(\"Request timed out\", \"TimeoutError\")),\n              timeout\n            );\n            return controller.signal;\n          }\n          return signal;\n        })();\n\n        try {\n          const requestInit: RequestInit = {\n            method,\n            headers: mergedHeaders,\n            credentials,\n            body: serializedBody as BodyInit | undefined,\n            signal: fetchSignal,\n          };\n\n          const response = await runInterceptors(this.interceptors, requestInit, (req) => fetch(resolvedUrl, req));\n\n          if (!response.ok) {\n            const rb = await parseBody(response, responseType, resolvedUrl);\n            const respHeaders = extractHeadersFrom(response);\n            throw new HttpError(response.status, response.statusText, rb, resolvedUrl, respHeaders);\n          }\n\n          if (observe === \"response\") {\n            return response;\n          }\n\n          const rb = await parseBody(response, responseType, resolvedUrl);\n          return transform(rb);\n        } finally {\n          if (timeoutId != null) clearTimeout(timeoutId);\n        }\n      },\n      (e: unknown) => (e instanceof HttpError ? e : toHttpError(e, resolvedUrl))\n    );\n  }\n}\n\n/**\n * Represents an HTTP error encountered during a request.\n *\n * Extends the native `Error` class with additional context: HTTP status code,\n * raw error message, response body, request URL, and response headers.\n */\nexport class HttpError extends Error {\n  public readonly status: number;\n  public readonly rawMessage: string;\n  public readonly body: unknown;\n  public readonly url: string;\n  public readonly headers?: Record<string, string>;\n\n  constructor(status: number, rawMessage: string, body: unknown, url: string, headers?: Record<string, string>) {\n    super(`Request to '${url}' failed with status ${status} and message: ${rawMessage}.`);\n    this.name = \"HttpError\";\n    this.status = status;\n    this.rawMessage = rawMessage;\n    this.body = body;\n    this.url = url;\n    this.headers = headers;\n  }\n}\n"],"mappings":"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"}

package/dist/monadyssey-fetch.d.ts

@@ -0,0 +1,231 @@
+import { IO } from '@openstage/monadyssey-core';
+
+/**
+ * Specifies the credentials policy for the request.
+ * - `"omit"`: Do not send credentials with the request.
+ * - `"same-origin"`: Send credentials only if the request is to the same origin.
+ * - `"include"`: Always send credentials with the request.
+ */
+export declare type Credentials = "omit" | "same-origin" | "include";
+
+/**
+ * A composable HTTP client that wraps the native `fetch` API, returning `IO` instances instead of Promises.
+ *
+ * Unlike v1, `HttpClient` is instantiable — each instance carries its own configuration (base URL,
+ * interceptors, default headers, timeout, credentials). This allows different parts of an application
+ * to use independently configured clients.
+ *
+ * All HTTP methods return `IO<HttpError, A | null>`, enabling lazy execution, functional composition,
+ * and explicit error handling. Cancellation is supported: when an IO is cancelled (via fiber or
+ * timeout), the underlying `fetch` call is aborted through `AbortSignal`.
+ *
+ * **On the `| null` in the return type:** when the server responds with `204 No Content` or
+ * `205 Reset Content`, there is no body to parse and the IO succeeds with `null`. This is a
+ * protocol-level fact (the HTTP spec says these statuses have no body), distinct from a
+ * domain-level optionality. For that reason the methods return `IO<HttpError, A | null>` rather
+ * than `IO<HttpError, Option<A>>`. `Option` is the right tool when a value might be absent at
+ * the domain level; `| null` is honest when the absence is structural to the protocol. For the
+ * 95% case where you control the endpoint and never receive 204, the `| null` is a brief
+ * `?? defaultValue` away.
+ *
+ * **Default credentials:** `same-origin`, matching the platform `fetch` default. Set
+ * `credentials: "include"` explicitly per-client or per-request if you need cookies to flow
+ * cross-origin.
+ *
+ * @example
+ * const api = new HttpClient({
+ *   baseUrl: "https://api.example.com",
+ *   interceptors: [authInterceptor],
+ *   defaultHeaders: { "Accept": "application/json" },
+ *   timeout: 5000,
+ * });
+ *
+ * const users = api.get<User[]>("/users");
+ */
+export declare class HttpClient {
+    private readonly interceptors;
+    private readonly baseUrl;
+    private readonly defaultHeaders;
+    private readonly defaultTimeout;
+    private readonly defaultCredentials;
+    /**
+     * Creates a new HttpClient with the given configuration.
+     *
+     * @param {HttpClientConfig} config - Configuration for the client.
+     */
+    constructor(config?: HttpClientConfig);
+    /**
+     * Performs a GET request.
+     *
+     * @template A - The expected type of the response body.
+     * @param {string} uri - The URL or path to request.
+     * @param {Omit<Options<A>, "body">} [options] - Request options (excluding body).
+     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     */
+    get(uri: string, options: Omit<Options, "body"> & {
+        observe: "response";
+    }): IO<HttpError, Response>;
+    get<A = any>(uri: string, options?: Omit<Options<A>, "body">): IO<HttpError, A | null>;
+    /**
+     * Performs a POST request.
+     *
+     * @template A - The expected type of the response body.
+     * @param {string} uri - The URL or path to request.
+     * @param {unknown} [body] - The request payload.
+     * @param {Options<A>} [options] - Request options.
+     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     */
+    post(uri: string, body: unknown, options: Options & {
+        observe: "response";
+    }): IO<HttpError, Response>;
+    post<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;
+    /**
+     * Performs a PUT request.
+     *
+     * @template A - The expected type of the response body.
+     * @param {string} uri - The URL or path to request.
+     * @param {unknown} [body] - The request payload.
+     * @param {Options<A>} [options] - Request options.
+     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     */
+    put(uri: string, body: unknown, options: Options & {
+        observe: "response";
+    }): IO<HttpError, Response>;
+    put<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;
+    /**
+     * Performs a PATCH request.
+     *
+     * @template A - The expected type of the response body.
+     * @param {string} uri - The URL or path to request.
+     * @param {unknown} [body] - The request payload.
+     * @param {Options<A>} [options] - Request options.
+     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     */
+    patch(uri: string, body: unknown, options: Options & {
+        observe: "response";
+    }): IO<HttpError, Response>;
+    patch<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;
+    /**
+     * Performs a DELETE request.
+     *
+     * @template A - The expected type of the response body.
+     * @param {string} uri - The URL or path to request.
+     * @param {Omit<Options<A>, "body">} [options] - Request options (excluding body).
+     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     */
+    delete(uri: string, options: Omit<Options, "body"> & {
+        observe: "response";
+    }): IO<HttpError, Response>;
+    delete<A = any>(uri: string, options?: Omit<Options<A>, "body">): IO<HttpError, A | null>;
+    /**
+     * Performs a custom HTTP request with the specified method.
+     *
+     * @template A - The expected type of the response body.
+     * @param {string} uri - The URL or path to request.
+     * @param {Method} method - The HTTP method.
+     * @param {Options<A>} [options] - Request options.
+     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     */
+    fetch(uri: string, method: Method, options: Options & {
+        observe: "response";
+    }): IO<HttpError, Response>;
+    fetch<A = any>(uri: string, method: Method, options?: Options<A>): IO<HttpError, A | null>;
+    private resolveUrl;
+    private request;
+}
+
+/**
+ * Configuration for creating an HttpClient instance.
+ */
+export declare type HttpClientConfig = {
+    /** Base URL prepended to relative paths. */
+    baseUrl?: string;
+    /** Interceptors applied in registration order (first registered = outermost). Immutable after construction. */
+    interceptors?: HttpInterceptor[];
+    /** Default headers merged into every request. Per-request headers take precedence. */
+    defaultHeaders?: Record<string, string>;
+    /** Default timeout in milliseconds for all requests. Can be overridden per-request. */
+    timeout?: number;
+    /** Default credentials policy. Defaults to `"same-origin"` (matches the platform `fetch` default). */
+    credentials?: Credentials;
+};
+
+/**
+ * Represents an HTTP error encountered during a request.
+ *
+ * Extends the native `Error` class with additional context: HTTP status code,
+ * raw error message, response body, request URL, and response headers.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly rawMessage: string;
+    readonly body: unknown;
+    readonly url: string;
+    readonly headers?: Record<string, string>;
+    constructor(status: number, rawMessage: string, body: unknown, url: string, headers?: Record<string, string>);
+}
+
+/**
+ * An HTTP interceptor that can modify or handle request and response data
+ * before and after an outgoing `fetch` call.
+ */
+export declare interface HttpInterceptor {
+    /**
+     * Intercepts an outgoing HTTP request.
+     *
+     * Call `next(request)` to continue the chain with the (optionally modified) request.
+     * Return a `Promise<Response>` without calling `next` to short-circuit the request.
+     *
+     * @param request - The configuration object for the pending `fetch` call.
+     * @param next - Forwards the request to the next interceptor or to `fetch`.
+     * @returns A Promise of the resulting `Response`.
+     */
+    intercept(request: RequestInit, next: (req: RequestInit) => Promise<Response>): Promise<Response>;
+}
+
+/**
+ * Represents the HTTP method for the request.
+ */
+export declare type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+
+/**
+ * Specifies how the response should be observed.
+ * - `"body"`: Return the response body.
+ * - `"response"`: Return the full `Response` object.
+ */
+export declare type Observe = "body" | "response";
+
+/**
+ * Options for configuring an individual HTTP request.
+ *
+ * @template A - The expected type of the response body after transformation.
+ */
+export declare type Options<A = any> = {
+    /** Custom headers for the request as key-value pairs. */
+    headers?: Record<string, string>;
+    /** The request payload. */
+    body?: unknown;
+    /** The expected type of the response body. Defaults to `"json"`. */
+    responseType?: ResponseType_2;
+    /** The credential policy for the request. Defaults to the client-level setting. */
+    credentials?: Credentials;
+    /** Specifies how the response should be observed. Defaults to `"body"`. */
+    observe?: Observe;
+    /** A function to transform the response body into the desired type. */
+    transform?: (data: unknown) => A;
+    /** Per-request timeout in milliseconds. Overrides the client-level timeout. */
+    timeout?: number;
+};
+
+/**
+ * Specifies the expected response type.
+ * - `"json"`: Parse the response as JSON.
+ * - `"text"`: Parse the response as text.
+ * - `"blob"`: Parse the response as a Blob.
+ * - `"arrayBuffer"`: Parse the response as an ArrayBuffer.
+ * - `"formData"`: Parse the response as FormData.
+ */
+declare type ResponseType_2 = "json" | "text" | "blob" | "arrayBuffer" | "formData";
+export { ResponseType_2 as ResponseType }
+
+export { }

package/dist/monadyssey-fetch.mjs

@@ -0,0 +1,122 @@
+import { IO as e } from "@openstage/monadyssey-core";
+//#region src/http-client.ts
+var t = (e) => typeof e != "object" || !e || e instanceof FormData || e instanceof Blob || e instanceof ArrayBuffer || e instanceof URLSearchParams || typeof ReadableStream < "u" && e instanceof ReadableStream || ArrayBuffer.isView(e), n = (e) => {
+	let t = {};
+	for (let [n, r] of Object.entries(e)) r !== void 0 && (t[n.toLowerCase()] = r);
+	return t;
+}, r = (e, t, n) => {
+	let r = n;
+	for (let t of [...e].reverse()) {
+		let e = r;
+		r = (n) => t.intercept(n, e);
+	}
+	return r(t);
+}, i = async (e, t, n) => {
+	if (e.status === 204 || e.status === 205) return null;
+	try {
+		switch (t) {
+			case "json": return await e.json();
+			case "text": return await e.text();
+			case "blob": return await e.blob();
+			case "arrayBuffer": return await e.arrayBuffer();
+			case "formData": return await e.formData();
+			default: throw a(`Unsupported response type: ${t}`, n, e);
+		}
+	} catch (t) {
+		throw t instanceof c ? t : a(t, n, e);
+	}
+}, a = (e, t, n) => {
+	let r = o(n), i = n ? n.body : null, a = e instanceof Error ? e.message : typeof e == "string" ? e : typeof e == "object" && e && "message" in e ? String(e.message) : "An unknown error occurred.";
+	return new c(n?.status || 500, a, i, t, r);
+}, o = (e) => {
+	if (!e) return {};
+	try {
+		return Object.fromEntries(e.headers.entries());
+	} catch {
+		return {};
+	}
+}, s = class {
+	interceptors;
+	baseUrl;
+	defaultHeaders;
+	defaultTimeout;
+	defaultCredentials;
+	constructor(e = {}) {
+		this.interceptors = Object.freeze([...e.interceptors ?? []]), this.baseUrl = e.baseUrl, this.defaultHeaders = e.defaultHeaders ?? {}, this.defaultTimeout = e.timeout, this.defaultCredentials = e.credentials ?? "same-origin";
+	}
+	get(e, t) {
+		return this.request(e, "GET", t);
+	}
+	post(e, t, n) {
+		return this.request(e, "POST", {
+			...n,
+			body: t
+		});
+	}
+	put(e, t, n) {
+		return this.request(e, "PUT", {
+			...n,
+			body: t
+		});
+	}
+	patch(e, t, n) {
+		return this.request(e, "PATCH", {
+			...n,
+			body: t
+		});
+	}
+	delete(e, t) {
+		return this.request(e, "DELETE", t);
+	}
+	fetch(e, t, n = {}) {
+		return this.request(e, t, n);
+	}
+	resolveUrl(e) {
+		if (!this.baseUrl) return e;
+		try {
+			return new URL(e), e;
+		} catch {
+			return `${this.baseUrl.endsWith("/") ? this.baseUrl.slice(0, -1) : this.baseUrl}${e.startsWith("/") ? e : `/${e}`}`;
+		}
+	}
+	request(s, l, u = {}) {
+		let d = this.resolveUrl(s), f = u.timeout ?? this.defaultTimeout;
+		return e.cancellable(async (e) => {
+			let { headers: a = {}, body: s, responseType: p = "json", credentials: m = this.defaultCredentials, observe: h = "body", transform: g = (e) => e } = u, _ = n({
+				...this.defaultHeaders,
+				...a
+			});
+			typeof s == "object" && s && !t(s) && !("content-type" in _) && (_["content-type"] = "application/json"), s instanceof FormData && delete _["content-type"];
+			let v = l === "GET" || l === "HEAD" || s == null ? void 0 : t(s) ? s : _["content-type"] === "application/json" ? JSON.stringify(s) : s, y, b, x = f == null ? e : (y = new AbortController(), e.addEventListener("abort", () => y.abort(e.reason), { once: !0 }), b = setTimeout(() => y.abort(new DOMException("Request timed out", "TimeoutError")), f), y.signal);
+			try {
+				let e = {
+					method: l,
+					headers: _,
+					credentials: m,
+					body: v,
+					signal: x
+				}, t = await r(this.interceptors, e, (e) => fetch(d, e));
+				if (!t.ok) {
+					let e = await i(t, p, d), n = o(t);
+					throw new c(t.status, t.statusText, e, d, n);
+				}
+				return h === "response" ? t : g(await i(t, p, d));
+			} finally {
+				b != null && clearTimeout(b);
+			}
+		}, (e) => e instanceof c ? e : a(e, d));
+	}
+}, c = class extends Error {
+	status;
+	rawMessage;
+	body;
+	url;
+	headers;
+	constructor(e, t, n, r, i) {
+		super(`Request to '${r}' failed with status ${e} and message: ${t}.`), this.name = "HttpError", this.status = e, this.rawMessage = t, this.body = n, this.url = r, this.headers = i;
+	}
+};
+//#endregion
+export { s as HttpClient, c as HttpError };
+
+//# sourceMappingURL=monadyssey-fetch.mjs.map

package/dist/monadyssey-fetch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"monadyssey-fetch.mjs","names":[],"sources":["../src/http-client.ts"],"sourcesContent":["import { IO } from \"@openstage/monadyssey-core\";\nimport { Credentials, HttpClientConfig, HttpInterceptor, Method, Options, ResponseType } from \"./options\";\n\n/**\n * Returns `true` if the body is a type that the fetch API knows how to send natively.\n * These types must NOT be JSON.stringified and must NOT have a Content-Type header auto-set\n * (the browser handles multipart boundaries for FormData, etc.).\n */\nconst isNativeBody = (body: unknown): boolean =>\n  typeof body !== \"object\" ||\n  body === null ||\n  body instanceof FormData ||\n  body instanceof Blob ||\n  body instanceof ArrayBuffer ||\n  body instanceof URLSearchParams ||\n  (typeof ReadableStream !== \"undefined\" && body instanceof ReadableStream) ||\n  ArrayBuffer.isView(body);\n\n/**\n * Normalizes header keys to lowercase for case-insensitive comparison.\n * HTTP header names are case-insensitive per RFC 7230.\n */\nconst normalizeHeaders = (headers: Record<string, string>): Record<string, string> => {\n  const result: Record<string, string> = {};\n  for (const [key, value] of Object.entries(headers)) {\n    if (value !== undefined) {\n      result[key.toLowerCase()] = value;\n    }\n  }\n  return result;\n};\n\n/**\n * Builds the interceptor chain as a pure function. No global state.\n * Interceptors are applied in registration order — first registered is outermost.\n */\nconst runInterceptors = (\n  interceptors: readonly HttpInterceptor[],\n  req: RequestInit,\n  fn: (req: RequestInit) => Promise<Response>\n): Promise<Response> => {\n  let next = fn;\n  for (const interceptor of [...interceptors].reverse()) {\n    const currentNext = next;\n    next = (r: RequestInit) => interceptor.intercept(r, currentNext);\n  }\n  return next(req);\n};\n\nconst parseBody = async (response: Response, responseType: ResponseType, url: string): Promise<unknown> => {\n  if (response.status === 204 || response.status === 205) {\n    return null;\n  }\n  try {\n    switch (responseType) {\n      case \"json\":\n        return await response.json();\n      case \"text\":\n        return await response.text();\n      case \"blob\":\n        return await response.blob();\n      case \"arrayBuffer\":\n        return await response.arrayBuffer();\n      case \"formData\":\n        return await response.formData();\n      default:\n        throw toHttpError(`Unsupported response type: ${responseType}`, url, response);\n    }\n  } catch (e: unknown) {\n    if (e instanceof HttpError) throw e;\n    throw toHttpError(e, url, response);\n  }\n};\n\nconst toHttpError = (e: unknown, uri: string, response?: Response): HttpError => {\n  const headers = extractHeadersFrom(response);\n  const body = response ? response.body : null;\n\n  const message =\n    e instanceof Error\n      ? e.message\n      : typeof e === \"string\"\n        ? e\n        : typeof e === \"object\" && e !== null && \"message\" in e\n          ? String((e as any).message)\n          : \"An unknown error occurred.\";\n\n  return new HttpError(response?.status || 500, message, body, uri, headers);\n};\n\nconst extractHeadersFrom = (response?: Response): Record<string, string> => {\n  if (!response) return {};\n  try {\n    return Object.fromEntries(response.headers.entries());\n  } catch {\n    return {};\n  }\n};\n\n/**\n * A composable HTTP client that wraps the native `fetch` API, returning `IO` instances instead of Promises.\n *\n * Unlike v1, `HttpClient` is instantiable — each instance carries its own configuration (base URL,\n * interceptors, default headers, timeout, credentials). This allows different parts of an application\n * to use independently configured clients.\n *\n * All HTTP methods return `IO<HttpError, A | null>`, enabling lazy execution, functional composition,\n * and explicit error handling. Cancellation is supported: when an IO is cancelled (via fiber or\n * timeout), the underlying `fetch` call is aborted through `AbortSignal`.\n *\n * **On the `| null` in the return type:** when the server responds with `204 No Content` or\n * `205 Reset Content`, there is no body to parse and the IO succeeds with `null`. This is a\n * protocol-level fact (the HTTP spec says these statuses have no body), distinct from a\n * domain-level optionality. For that reason the methods return `IO<HttpError, A | null>` rather\n * than `IO<HttpError, Option<A>>`. `Option` is the right tool when a value might be absent at\n * the domain level; `| null` is honest when the absence is structural to the protocol. For the\n * 95% case where you control the endpoint and never receive 204, the `| null` is a brief\n * `?? defaultValue` away.\n *\n * **Default credentials:** `same-origin`, matching the platform `fetch` default. Set\n * `credentials: \"include\"` explicitly per-client or per-request if you need cookies to flow\n * cross-origin.\n *\n * @example\n * const api = new HttpClient({\n *   baseUrl: \"https://api.example.com\",\n *   interceptors: [authInterceptor],\n *   defaultHeaders: { \"Accept\": \"application/json\" },\n *   timeout: 5000,\n * });\n *\n * const users = api.get<User[]>(\"/users\");\n */\nexport class HttpClient {\n  private readonly interceptors: readonly HttpInterceptor[];\n  private readonly baseUrl: string | undefined;\n  private readonly defaultHeaders: Record<string, string>;\n  private readonly defaultTimeout: number | undefined;\n  private readonly defaultCredentials: Credentials;\n\n  /**\n   * Creates a new HttpClient with the given configuration.\n   *\n   * @param {HttpClientConfig} config - Configuration for the client.\n   */\n  constructor(config: HttpClientConfig = {}) {\n    this.interceptors = Object.freeze([...(config.interceptors ?? [])]);\n    this.baseUrl = config.baseUrl;\n    this.defaultHeaders = config.defaultHeaders ?? {};\n    this.defaultTimeout = config.timeout;\n    this.defaultCredentials = config.credentials ?? \"same-origin\";\n  }\n\n  /**\n   * Performs a GET request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Omit<Options<A>, \"body\">} [options] - Request options (excluding body).\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  get(uri: string, options: Omit<Options, \"body\"> & { observe: \"response\" }): IO<HttpError, Response>;\n  get<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, A | null>;\n  get<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"GET\", options);\n  }\n\n  /**\n   * Performs a POST request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  post(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  post<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  post<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"POST\", { ...options, body });\n  }\n\n  /**\n   * Performs a PUT request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  put(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  put<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  put<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"PUT\", { ...options, body });\n  }\n\n  /**\n   * Performs a PATCH request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  patch(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  patch<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  patch<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"PATCH\", { ...options, body });\n  }\n\n  /**\n   * Performs a DELETE request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Omit<Options<A>, \"body\">} [options] - Request options (excluding body).\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  delete(uri: string, options: Omit<Options, \"body\"> & { observe: \"response\" }): IO<HttpError, Response>;\n  delete<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, A | null>;\n  delete<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"DELETE\", options);\n  }\n\n  /**\n   * Performs a custom HTTP request with the specified method.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Method} method - The HTTP method.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  fetch(uri: string, method: Method, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  fetch<A = any>(uri: string, method: Method, options?: Options<A>): IO<HttpError, A | null>;\n  fetch<A = any>(uri: string, method: Method, options: Options<A> = {}): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, method, options);\n  }\n\n  private resolveUrl(uri: string): string {\n    if (!this.baseUrl) return uri;\n    try {\n      new URL(uri);\n      return uri;\n    } catch {\n      const base = this.baseUrl.endsWith(\"/\") ? this.baseUrl.slice(0, -1) : this.baseUrl;\n      const path = uri.startsWith(\"/\") ? uri : `/${uri}`;\n      return `${base}${path}`;\n    }\n  }\n\n  private request<A = any>(uri: string, method: Method, options: Options<A> = {}): IO<HttpError, Response | A | null> {\n    const resolvedUrl = this.resolveUrl(uri);\n    const timeout = options.timeout ?? this.defaultTimeout;\n\n    return IO.cancellable<HttpError, Response | A | null>(\n      async (signal: AbortSignal) => {\n        const {\n          headers = {},\n          body,\n          responseType = \"json\",\n          credentials = this.defaultCredentials,\n          observe = \"body\",\n          transform = (data: unknown) => data as A,\n        } = options;\n\n        // Merge default headers + per-request headers, all lowercased\n        const mergedHeaders = normalizeHeaders({ ...this.defaultHeaders, ...headers });\n\n        // Auto-detect Content-Type only for plain objects (not FormData, Blob, etc.)\n        const shouldAutoJson =\n          body != null && typeof body === \"object\" && !isNativeBody(body) && !(\"content-type\" in mergedHeaders);\n\n        if (shouldAutoJson) {\n          mergedHeaders[\"content-type\"] = \"application/json\";\n        }\n\n        // For FormData, do NOT set Content-Type — the browser sets the multipart boundary\n        if (body instanceof FormData) {\n          delete mergedHeaders[\"content-type\"];\n        }\n\n        // Serialize body\n        const serializedBody =\n          method === \"GET\" || method === \"HEAD\" || body == null\n            ? undefined\n            : isNativeBody(body)\n              ? body\n              : mergedHeaders[\"content-type\"] === \"application/json\"\n                ? JSON.stringify(body)\n                : body;\n\n        // Timeout support: create a child controller that aborts on timeout or parent signal\n        let controller: AbortController | undefined;\n        let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n        const fetchSignal = (() => {\n          if (timeout != null) {\n            controller = new AbortController();\n            const onParentAbort = () => controller!.abort(signal.reason);\n            signal.addEventListener(\"abort\", onParentAbort, { once: true });\n            timeoutId = setTimeout(\n              () => controller!.abort(new DOMException(\"Request timed out\", \"TimeoutError\")),\n              timeout\n            );\n            return controller.signal;\n          }\n          return signal;\n        })();\n\n        try {\n          const requestInit: RequestInit = {\n            method,\n            headers: mergedHeaders,\n            credentials,\n            body: serializedBody as BodyInit | undefined,\n            signal: fetchSignal,\n          };\n\n          const response = await runInterceptors(this.interceptors, requestInit, (req) => fetch(resolvedUrl, req));\n\n          if (!response.ok) {\n            const rb = await parseBody(response, responseType, resolvedUrl);\n            const respHeaders = extractHeadersFrom(response);\n            throw new HttpError(response.status, response.statusText, rb, resolvedUrl, respHeaders);\n          }\n\n          if (observe === \"response\") {\n            return response;\n          }\n\n          const rb = await parseBody(response, responseType, resolvedUrl);\n          return transform(rb);\n        } finally {\n          if (timeoutId != null) clearTimeout(timeoutId);\n        }\n      },\n      (e: unknown) => (e instanceof HttpError ? e : toHttpError(e, resolvedUrl))\n    );\n  }\n}\n\n/**\n * Represents an HTTP error encountered during a request.\n *\n * Extends the native `Error` class with additional context: HTTP status code,\n * raw error message, response body, request URL, and response headers.\n */\nexport class HttpError extends Error {\n  public readonly status: number;\n  public readonly rawMessage: string;\n  public readonly body: unknown;\n  public readonly url: string;\n  public readonly headers?: Record<string, string>;\n\n  constructor(status: number, rawMessage: string, body: unknown, url: string, headers?: Record<string, string>) {\n    super(`Request to '${url}' failed with status ${status} and message: ${rawMessage}.`);\n    this.name = \"HttpError\";\n    this.status = status;\n    this.rawMessage = rawMessage;\n    this.body = body;\n    this.url = url;\n    this.headers = headers;\n  }\n}\n"],"mappings":";;AAQA,IAAM,KAAgB,MACpB,OAAO,KAAS,aAChB,KACA,aAAgB,YAChB,aAAgB,QAChB,aAAgB,eAChB,aAAgB,mBACf,OAAO,iBAAmB,OAAe,aAAgB,kBAC1D,YAAY,OAAO,EAAK,EAMpB,KAAoB,MAA4D;CACpF,IAAM,IAAiC,EAAE;AACzC,MAAK,IAAM,CAAC,GAAK,MAAU,OAAO,QAAQ,EAAQ,CAChD,CAAI,MAAU,KAAA,MACZ,EAAO,EAAI,aAAa,IAAI;AAGhC,QAAO;GAOH,KACJ,GACA,GACA,MACsB;CACtB,IAAI,IAAO;AACX,MAAK,IAAM,KAAe,CAAC,GAAG,EAAa,CAAC,SAAS,EAAE;EACrD,IAAM,IAAc;AACpB,OAAQ,MAAmB,EAAY,UAAU,GAAG,EAAY;;AAElE,QAAO,EAAK,EAAI;GAGZ,IAAY,OAAO,GAAoB,GAA4B,MAAkC;AACzG,KAAI,EAAS,WAAW,OAAO,EAAS,WAAW,IACjD,QAAO;AAET,KAAI;AACF,UAAQ,GAAR;GACE,KAAK,OACH,QAAO,MAAM,EAAS,MAAM;GAC9B,KAAK,OACH,QAAO,MAAM,EAAS,MAAM;GAC9B,KAAK,OACH,QAAO,MAAM,EAAS,MAAM;GAC9B,KAAK,cACH,QAAO,MAAM,EAAS,aAAa;GACrC,KAAK,WACH,QAAO,MAAM,EAAS,UAAU;GAClC,QACE,OAAM,EAAY,8BAA8B,KAAgB,GAAK,EAAS;;UAE3E,GAAY;AAEnB,QADI,aAAa,IAAiB,IAC5B,EAAY,GAAG,GAAK,EAAS;;GAIjC,KAAe,GAAY,GAAa,MAAmC;CAC/E,IAAM,IAAU,EAAmB,EAAS,EACtC,IAAO,IAAW,EAAS,OAAO,MAElC,IACJ,aAAa,QACT,EAAE,UACF,OAAO,KAAM,WACX,IACA,OAAO,KAAM,YAAY,KAAc,aAAa,IAClD,OAAQ,EAAU,QAAQ,GAC1B;AAEV,QAAO,IAAI,EAAU,GAAU,UAAU,KAAK,GAAS,GAAM,GAAK,EAAQ;GAGtE,KAAsB,MAAgD;AAC1E,KAAI,CAAC,EAAU,QAAO,EAAE;AACxB,KAAI;AACF,SAAO,OAAO,YAAY,EAAS,QAAQ,SAAS,CAAC;SAC/C;AACN,SAAO,EAAE;;GAsCA,IAAb,MAAwB;CACtB;CACA;CACA;CACA;CACA;CAOA,YAAY,IAA2B,EAAE,EAAE;AAKzC,EAJA,KAAK,eAAe,OAAO,OAAO,CAAC,GAAI,EAAO,gBAAgB,EAAE,CAAE,CAAC,EACnE,KAAK,UAAU,EAAO,SACtB,KAAK,iBAAiB,EAAO,kBAAkB,EAAE,EACjD,KAAK,iBAAiB,EAAO,SAC7B,KAAK,qBAAqB,EAAO,eAAe;;CAalD,IAAa,GAAa,GAAwE;AAChG,SAAO,KAAK,QAAW,GAAK,OAAO,EAAQ;;CAc7C,KAAc,GAAa,GAAgB,GAA0D;AACnG,SAAO,KAAK,QAAW,GAAK,QAAQ;GAAE,GAAG;GAAS;GAAM,CAAC;;CAc3D,IAAa,GAAa,GAAgB,GAA0D;AAClG,SAAO,KAAK,QAAW,GAAK,OAAO;GAAE,GAAG;GAAS;GAAM,CAAC;;CAc1D,MAAe,GAAa,GAAgB,GAA0D;AACpG,SAAO,KAAK,QAAW,GAAK,SAAS;GAAE,GAAG;GAAS;GAAM,CAAC;;CAa5D,OAAgB,GAAa,GAAwE;AACnG,SAAO,KAAK,QAAW,GAAK,UAAU,EAAQ;;CAchD,MAAe,GAAa,GAAgB,IAAsB,EAAE,EAAsC;AACxG,SAAO,KAAK,QAAW,GAAK,GAAQ,EAAQ;;CAG9C,WAAmB,GAAqB;AACtC,MAAI,CAAC,KAAK,QAAS,QAAO;AAC1B,MAAI;AAEF,UADA,IAAI,IAAI,EAAI,EACL;UACD;AAGN,UAAO,GAFM,KAAK,QAAQ,SAAS,IAAI,GAAG,KAAK,QAAQ,MAAM,GAAG,GAAG,GAAG,KAAK,UAC9D,EAAI,WAAW,IAAI,GAAG,IAAM,IAAI;;;CAKjD,QAAyB,GAAa,GAAgB,IAAsB,EAAE,EAAsC;EAClH,IAAM,IAAc,KAAK,WAAW,EAAI,EAClC,IAAU,EAAQ,WAAW,KAAK;AAExC,SAAO,EAAG,YACR,OAAO,MAAwB;GAC7B,IAAM,EACJ,aAAU,EAAE,EACZ,SACA,kBAAe,QACf,iBAAc,KAAK,oBACnB,aAAU,QACV,gBAAa,MAAkB,MAC7B,GAGE,IAAgB,EAAiB;IAAE,GAAG,KAAK;IAAgB,GAAG;IAAS,CAAC;AAW9E,GAPkB,OAAO,KAAS,YAAhC,KAA4C,CAAC,EAAa,EAAK,IAAI,EAAE,kBAAkB,OAGvF,EAAc,kBAAkB,qBAI9B,aAAgB,YAClB,OAAO,EAAc;GAIvB,IAAM,IACJ,MAAW,SAAS,MAAW,UAAU,KAAQ,OAC7C,KAAA,IACA,EAAa,EAAK,GAChB,IACA,EAAc,oBAAoB,qBAChC,KAAK,UAAU,EAAK,GACpB,GAGN,GACA,GAEE,IACA,KAAW,OAUR,KATL,IAAa,IAAI,iBAAiB,EAElC,EAAO,iBAAiB,eADI,EAAY,MAAM,EAAO,OAAO,EACZ,EAAE,MAAM,IAAM,CAAC,EAC/D,IAAY,iBACJ,EAAY,MAAM,IAAI,aAAa,qBAAqB,eAAe,CAAC,EAC9E,EACD,EACM,EAAW;AAKtB,OAAI;IACF,IAAM,IAA2B;KAC/B;KACA,SAAS;KACT;KACA,MAAM;KACN,QAAQ;KACT,EAEK,IAAW,MAAM,EAAgB,KAAK,cAAc,IAAc,MAAQ,MAAM,GAAa,EAAI,CAAC;AAExG,QAAI,CAAC,EAAS,IAAI;KAChB,IAAM,IAAK,MAAM,EAAU,GAAU,GAAc,EAAY,EACzD,IAAc,EAAmB,EAAS;AAChD,WAAM,IAAI,EAAU,EAAS,QAAQ,EAAS,YAAY,GAAI,GAAa,EAAY;;AAQzF,WALI,MAAY,aACP,IAIF,EADI,MAAM,EAAU,GAAU,GAAc,EAAY,CAC3C;aACZ;AACR,IAAI,KAAa,QAAM,aAAa,EAAU;;MAGjD,MAAgB,aAAa,IAAY,IAAI,EAAY,GAAG,EAAY,CAC1E;;GAUQ,IAAb,cAA+B,MAAM;CACnC;CACA;CACA;CACA;CACA;CAEA,YAAY,GAAgB,GAAoB,GAAe,GAAa,GAAkC;AAO5G,EANA,MAAM,eAAe,EAAI,uBAAuB,EAAO,gBAAgB,EAAW,GAAG,EACrF,KAAK,OAAO,aACZ,KAAK,SAAS,GACd,KAAK,aAAa,GAClB,KAAK,OAAO,GACZ,KAAK,MAAM,GACX,KAAK,UAAU"}

package/dist/monadyssey-fetch.umd.js

@@ -0,0 +1,2 @@
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require(`@openstage/monadyssey-core`)):typeof define==`function`&&define.amd?define([`exports`,`@openstage/monadyssey-core`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e[`monadyssey-fetch`]={},e.Monadyssey))})(this,function(e,t){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var n=e=>typeof e!=`object`||!e||e instanceof FormData||e instanceof Blob||e instanceof ArrayBuffer||e instanceof URLSearchParams||typeof ReadableStream<`u`&&e instanceof ReadableStream||ArrayBuffer.isView(e),r=e=>{let t={};for(let[n,r]of Object.entries(e))r!==void 0&&(t[n.toLowerCase()]=r);return t},i=(e,t,n)=>{let r=n;for(let t of[...e].reverse()){let e=r;r=n=>t.intercept(n,e)}return r(t)},a=async(e,t,n)=>{if(e.status===204||e.status===205)return null;try{switch(t){case`json`:return await e.json();case`text`:return await e.text();case`blob`:return await e.blob();case`arrayBuffer`:return await e.arrayBuffer();case`formData`:return await e.formData();default:throw o(`Unsupported response type: ${t}`,n,e)}}catch(t){throw t instanceof l?t:o(t,n,e)}},o=(e,t,n)=>{let r=s(n),i=n?n.body:null,a=e instanceof Error?e.message:typeof e==`string`?e:typeof e==`object`&&e&&`message`in e?String(e.message):`An unknown error occurred.`;return new l(n?.status||500,a,i,t,r)},s=e=>{if(!e)return{};try{return Object.fromEntries(e.headers.entries())}catch{return{}}},c=class{interceptors;baseUrl;defaultHeaders;defaultTimeout;defaultCredentials;constructor(e={}){this.interceptors=Object.freeze([...e.interceptors??[]]),this.baseUrl=e.baseUrl,this.defaultHeaders=e.defaultHeaders??{},this.defaultTimeout=e.timeout,this.defaultCredentials=e.credentials??`same-origin`}get(e,t){return this.request(e,`GET`,t)}post(e,t,n){return this.request(e,`POST`,{...n,body:t})}put(e,t,n){return this.request(e,`PUT`,{...n,body:t})}patch(e,t,n){return this.request(e,`PATCH`,{...n,body:t})}delete(e,t){return this.request(e,`DELETE`,t)}fetch(e,t,n={}){return this.request(e,t,n)}resolveUrl(e){if(!this.baseUrl)return e;try{return new URL(e),e}catch{return`${this.baseUrl.endsWith(`/`)?this.baseUrl.slice(0,-1):this.baseUrl}${e.startsWith(`/`)?e:`/${e}`}`}}request(e,c,u={}){let d=this.resolveUrl(e),f=u.timeout??this.defaultTimeout;return t.IO.cancellable(async e=>{let{headers:t={},body:o,responseType:p=`json`,credentials:m=this.defaultCredentials,observe:h=`body`,transform:g=e=>e}=u,_=r({...this.defaultHeaders,...t});typeof o==`object`&&o&&!n(o)&&!(`content-type`in _)&&(_[`content-type`]=`application/json`),o instanceof FormData&&delete _[`content-type`];let v=c===`GET`||c===`HEAD`||o==null?void 0:n(o)?o:_[`content-type`]===`application/json`?JSON.stringify(o):o,y,b,x=f==null?e:(y=new AbortController,e.addEventListener(`abort`,()=>y.abort(e.reason),{once:!0}),b=setTimeout(()=>y.abort(new DOMException(`Request timed out`,`TimeoutError`)),f),y.signal);try{let e={method:c,headers:_,credentials:m,body:v,signal:x},t=await i(this.interceptors,e,e=>fetch(d,e));if(!t.ok){let e=await a(t,p,d),n=s(t);throw new l(t.status,t.statusText,e,d,n)}return h===`response`?t:g(await a(t,p,d))}finally{b!=null&&clearTimeout(b)}},e=>e instanceof l?e:o(e,d))}},l=class extends Error{status;rawMessage;body;url;headers;constructor(e,t,n,r,i){super(`Request to '${r}' failed with status ${e} and message: ${t}.`),this.name=`HttpError`,this.status=e,this.rawMessage=t,this.body=n,this.url=r,this.headers=i}};e.HttpClient=c,e.HttpError=l});
+//# sourceMappingURL=monadyssey-fetch.umd.js.map

package/dist/monadyssey-fetch.umd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"monadyssey-fetch.umd.js","names":[],"sources":["../src/http-client.ts"],"sourcesContent":["import { IO } from \"@openstage/monadyssey-core\";\nimport { Credentials, HttpClientConfig, HttpInterceptor, Method, Options, ResponseType } from \"./options\";\n\n/**\n * Returns `true` if the body is a type that the fetch API knows how to send natively.\n * These types must NOT be JSON.stringified and must NOT have a Content-Type header auto-set\n * (the browser handles multipart boundaries for FormData, etc.).\n */\nconst isNativeBody = (body: unknown): boolean =>\n  typeof body !== \"object\" ||\n  body === null ||\n  body instanceof FormData ||\n  body instanceof Blob ||\n  body instanceof ArrayBuffer ||\n  body instanceof URLSearchParams ||\n  (typeof ReadableStream !== \"undefined\" && body instanceof ReadableStream) ||\n  ArrayBuffer.isView(body);\n\n/**\n * Normalizes header keys to lowercase for case-insensitive comparison.\n * HTTP header names are case-insensitive per RFC 7230.\n */\nconst normalizeHeaders = (headers: Record<string, string>): Record<string, string> => {\n  const result: Record<string, string> = {};\n  for (const [key, value] of Object.entries(headers)) {\n    if (value !== undefined) {\n      result[key.toLowerCase()] = value;\n    }\n  }\n  return result;\n};\n\n/**\n * Builds the interceptor chain as a pure function. No global state.\n * Interceptors are applied in registration order — first registered is outermost.\n */\nconst runInterceptors = (\n  interceptors: readonly HttpInterceptor[],\n  req: RequestInit,\n  fn: (req: RequestInit) => Promise<Response>\n): Promise<Response> => {\n  let next = fn;\n  for (const interceptor of [...interceptors].reverse()) {\n    const currentNext = next;\n    next = (r: RequestInit) => interceptor.intercept(r, currentNext);\n  }\n  return next(req);\n};\n\nconst parseBody = async (response: Response, responseType: ResponseType, url: string): Promise<unknown> => {\n  if (response.status === 204 || response.status === 205) {\n    return null;\n  }\n  try {\n    switch (responseType) {\n      case \"json\":\n        return await response.json();\n      case \"text\":\n        return await response.text();\n      case \"blob\":\n        return await response.blob();\n      case \"arrayBuffer\":\n        return await response.arrayBuffer();\n      case \"formData\":\n        return await response.formData();\n      default:\n        throw toHttpError(`Unsupported response type: ${responseType}`, url, response);\n    }\n  } catch (e: unknown) {\n    if (e instanceof HttpError) throw e;\n    throw toHttpError(e, url, response);\n  }\n};\n\nconst toHttpError = (e: unknown, uri: string, response?: Response): HttpError => {\n  const headers = extractHeadersFrom(response);\n  const body = response ? response.body : null;\n\n  const message =\n    e instanceof Error\n      ? e.message\n      : typeof e === \"string\"\n        ? e\n        : typeof e === \"object\" && e !== null && \"message\" in e\n          ? String((e as any).message)\n          : \"An unknown error occurred.\";\n\n  return new HttpError(response?.status || 500, message, body, uri, headers);\n};\n\nconst extractHeadersFrom = (response?: Response): Record<string, string> => {\n  if (!response) return {};\n  try {\n    return Object.fromEntries(response.headers.entries());\n  } catch {\n    return {};\n  }\n};\n\n/**\n * A composable HTTP client that wraps the native `fetch` API, returning `IO` instances instead of Promises.\n *\n * Unlike v1, `HttpClient` is instantiable — each instance carries its own configuration (base URL,\n * interceptors, default headers, timeout, credentials). This allows different parts of an application\n * to use independently configured clients.\n *\n * All HTTP methods return `IO<HttpError, A | null>`, enabling lazy execution, functional composition,\n * and explicit error handling. Cancellation is supported: when an IO is cancelled (via fiber or\n * timeout), the underlying `fetch` call is aborted through `AbortSignal`.\n *\n * **On the `| null` in the return type:** when the server responds with `204 No Content` or\n * `205 Reset Content`, there is no body to parse and the IO succeeds with `null`. This is a\n * protocol-level fact (the HTTP spec says these statuses have no body), distinct from a\n * domain-level optionality. For that reason the methods return `IO<HttpError, A | null>` rather\n * than `IO<HttpError, Option<A>>`. `Option` is the right tool when a value might be absent at\n * the domain level; `| null` is honest when the absence is structural to the protocol. For the\n * 95% case where you control the endpoint and never receive 204, the `| null` is a brief\n * `?? defaultValue` away.\n *\n * **Default credentials:** `same-origin`, matching the platform `fetch` default. Set\n * `credentials: \"include\"` explicitly per-client or per-request if you need cookies to flow\n * cross-origin.\n *\n * @example\n * const api = new HttpClient({\n *   baseUrl: \"https://api.example.com\",\n *   interceptors: [authInterceptor],\n *   defaultHeaders: { \"Accept\": \"application/json\" },\n *   timeout: 5000,\n * });\n *\n * const users = api.get<User[]>(\"/users\");\n */\nexport class HttpClient {\n  private readonly interceptors: readonly HttpInterceptor[];\n  private readonly baseUrl: string | undefined;\n  private readonly defaultHeaders: Record<string, string>;\n  private readonly defaultTimeout: number | undefined;\n  private readonly defaultCredentials: Credentials;\n\n  /**\n   * Creates a new HttpClient with the given configuration.\n   *\n   * @param {HttpClientConfig} config - Configuration for the client.\n   */\n  constructor(config: HttpClientConfig = {}) {\n    this.interceptors = Object.freeze([...(config.interceptors ?? [])]);\n    this.baseUrl = config.baseUrl;\n    this.defaultHeaders = config.defaultHeaders ?? {};\n    this.defaultTimeout = config.timeout;\n    this.defaultCredentials = config.credentials ?? \"same-origin\";\n  }\n\n  /**\n   * Performs a GET request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Omit<Options<A>, \"body\">} [options] - Request options (excluding body).\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  get(uri: string, options: Omit<Options, \"body\"> & { observe: \"response\" }): IO<HttpError, Response>;\n  get<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, A | null>;\n  get<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"GET\", options);\n  }\n\n  /**\n   * Performs a POST request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  post(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  post<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  post<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"POST\", { ...options, body });\n  }\n\n  /**\n   * Performs a PUT request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  put(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  put<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  put<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"PUT\", { ...options, body });\n  }\n\n  /**\n   * Performs a PATCH request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {unknown} [body] - The request payload.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  patch(uri: string, body: unknown, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  patch<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;\n  patch<A = any>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"PATCH\", { ...options, body });\n  }\n\n  /**\n   * Performs a DELETE request.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Omit<Options<A>, \"body\">} [options] - Request options (excluding body).\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  delete(uri: string, options: Omit<Options, \"body\"> & { observe: \"response\" }): IO<HttpError, Response>;\n  delete<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, A | null>;\n  delete<A = any>(uri: string, options?: Omit<Options<A>, \"body\">): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, \"DELETE\", options);\n  }\n\n  /**\n   * Performs a custom HTTP request with the specified method.\n   *\n   * @template A - The expected type of the response body.\n   * @param {string} uri - The URL or path to request.\n   * @param {Method} method - The HTTP method.\n   * @param {Options<A>} [options] - Request options.\n   * @returns {IO<HttpError, A | null>} An IO representing the result.\n   */\n  fetch(uri: string, method: Method, options: Options & { observe: \"response\" }): IO<HttpError, Response>;\n  fetch<A = any>(uri: string, method: Method, options?: Options<A>): IO<HttpError, A | null>;\n  fetch<A = any>(uri: string, method: Method, options: Options<A> = {}): IO<HttpError, Response | A | null> {\n    return this.request<A>(uri, method, options);\n  }\n\n  private resolveUrl(uri: string): string {\n    if (!this.baseUrl) return uri;\n    try {\n      new URL(uri);\n      return uri;\n    } catch {\n      const base = this.baseUrl.endsWith(\"/\") ? this.baseUrl.slice(0, -1) : this.baseUrl;\n      const path = uri.startsWith(\"/\") ? uri : `/${uri}`;\n      return `${base}${path}`;\n    }\n  }\n\n  private request<A = any>(uri: string, method: Method, options: Options<A> = {}): IO<HttpError, Response | A | null> {\n    const resolvedUrl = this.resolveUrl(uri);\n    const timeout = options.timeout ?? this.defaultTimeout;\n\n    return IO.cancellable<HttpError, Response | A | null>(\n      async (signal: AbortSignal) => {\n        const {\n          headers = {},\n          body,\n          responseType = \"json\",\n          credentials = this.defaultCredentials,\n          observe = \"body\",\n          transform = (data: unknown) => data as A,\n        } = options;\n\n        // Merge default headers + per-request headers, all lowercased\n        const mergedHeaders = normalizeHeaders({ ...this.defaultHeaders, ...headers });\n\n        // Auto-detect Content-Type only for plain objects (not FormData, Blob, etc.)\n        const shouldAutoJson =\n          body != null && typeof body === \"object\" && !isNativeBody(body) && !(\"content-type\" in mergedHeaders);\n\n        if (shouldAutoJson) {\n          mergedHeaders[\"content-type\"] = \"application/json\";\n        }\n\n        // For FormData, do NOT set Content-Type — the browser sets the multipart boundary\n        if (body instanceof FormData) {\n          delete mergedHeaders[\"content-type\"];\n        }\n\n        // Serialize body\n        const serializedBody =\n          method === \"GET\" || method === \"HEAD\" || body == null\n            ? undefined\n            : isNativeBody(body)\n              ? body\n              : mergedHeaders[\"content-type\"] === \"application/json\"\n                ? JSON.stringify(body)\n                : body;\n\n        // Timeout support: create a child controller that aborts on timeout or parent signal\n        let controller: AbortController | undefined;\n        let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n        const fetchSignal = (() => {\n          if (timeout != null) {\n            controller = new AbortController();\n            const onParentAbort = () => controller!.abort(signal.reason);\n            signal.addEventListener(\"abort\", onParentAbort, { once: true });\n            timeoutId = setTimeout(\n              () => controller!.abort(new DOMException(\"Request timed out\", \"TimeoutError\")),\n              timeout\n            );\n            return controller.signal;\n          }\n          return signal;\n        })();\n\n        try {\n          const requestInit: RequestInit = {\n            method,\n            headers: mergedHeaders,\n            credentials,\n            body: serializedBody as BodyInit | undefined,\n            signal: fetchSignal,\n          };\n\n          const response = await runInterceptors(this.interceptors, requestInit, (req) => fetch(resolvedUrl, req));\n\n          if (!response.ok) {\n            const rb = await parseBody(response, responseType, resolvedUrl);\n            const respHeaders = extractHeadersFrom(response);\n            throw new HttpError(response.status, response.statusText, rb, resolvedUrl, respHeaders);\n          }\n\n          if (observe === \"response\") {\n            return response;\n          }\n\n          const rb = await parseBody(response, responseType, resolvedUrl);\n          return transform(rb);\n        } finally {\n          if (timeoutId != null) clearTimeout(timeoutId);\n        }\n      },\n      (e: unknown) => (e instanceof HttpError ? e : toHttpError(e, resolvedUrl))\n    );\n  }\n}\n\n/**\n * Represents an HTTP error encountered during a request.\n *\n * Extends the native `Error` class with additional context: HTTP status code,\n * raw error message, response body, request URL, and response headers.\n */\nexport class HttpError extends Error {\n  public readonly status: number;\n  public readonly rawMessage: string;\n  public readonly body: unknown;\n  public readonly url: string;\n  public readonly headers?: Record<string, string>;\n\n  constructor(status: number, rawMessage: string, body: unknown, url: string, headers?: Record<string, string>) {\n    super(`Request to '${url}' failed with status ${status} and message: ${rawMessage}.`);\n    this.name = \"HttpError\";\n    this.status = status;\n    this.rawMessage = rawMessage;\n    this.body = body;\n    this.url = url;\n    this.headers = headers;\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@openstage/monadyssey-fetch",
+  "version": "3.0.0-beta.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/open-stage/monadyssey.git"
+  },
+  "keywords": [
+    "functional programming",
+    "typescript",
+    "http",
+    "fetch"
+  ],
+  "author": "Gabriel Bornea",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/monadyssey-fetch.cjs",
+  "module": "./dist/monadyssey-fetch.mjs",
+  "typings": "./dist/monadyssey-fetch.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/monadyssey-fetch.d.ts",
+      "import": "./dist/monadyssey-fetch.mjs",
+      "require": "./dist/monadyssey-fetch.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "npx jest --verbose --coverage --config ../../jest.config.cjs --detectOpenHandles",
+    "build": "npx tsc && npx vite build --config vite.config.ts",
+    "format": "npm run lint:fix && npm run prettier:fix",
+    "lint": "npx eslint \"src/**/*.{ts,tsx}\" \"test/**/*.{ts,tsx}\"",
+    "lint:fix": "npm run lint -- --fix",
+    "prettier": "npx prettier \"src/**/*.{ts,tsx}\" \"test/**/*.{ts,tsx}\" --check",
+    "prettier:fix": "npm run prettier -- --write"
+  },
+  "peerDependencies": {
+    "@openstage/monadyssey-core": "^3.0.0-beta.1"
+  }
+}

package/readme.md

@@ -0,0 +1,123 @@
+[![npm version](https://img.shields.io/npm/v/@openstage/monadyssey-fetch.svg)](https://www.npmjs.com/package/@openstage/monadyssey-fetch)
+[![Documentation](https://img.shields.io/badge/docs-online-brightgreen)](../../docs/monadyssey-fetch)
+
+### Overview
+
+**@openstage/monadyssey-fetch** is an HTTP client module designed to provide a functional and composable interface for making
+HTTP requests. It leverages `IO` and other functional constructs from **@openstage/monadyssey-core** to ensure predictable
+error handling, declarative workflows, and type safety when interacting with APIs.
+
+### Documentation
+
+Explore the documentation for specific features:
+
+- [HttpClient](../../docs/monadyssey-fetch/http-client.md): Composable HTTP client with base URL, interceptors, cancellation, timeout, and native body type support.
+
+### Installation
+
+To use `@openstage/monadyssey-fetch` in your project, install it via npm:
+
+```
+npm install @openstage/monadyssey-fetch @openstage/monadyssey-core
+```
+
+### Features
+
+#### Instance-Based Configuration
+
+Each `HttpClient` instance carries its own configuration — base URL, interceptors, default headers, timeout, and
+credentials. Different parts of an application can use independently configured clients.
+
+#### Cancellation
+
+Cancelling an IO (via `fiber.cancel()` or `IO.timeout`) aborts the underlying `fetch` call through `AbortSignal`.
+No network resources are wasted on cancelled requests.
+
+#### Timeout
+
+Configurable at both client level and per-request. When a timeout fires, the HTTP request is aborted.
+
+#### Native Body Types
+
+`FormData`, `Blob`, `File`, `ArrayBuffer`, `URLSearchParams`, and `ReadableStream` are passed directly to `fetch`
+without JSON serialization. For `FormData`, no `Content-Type` header is set — the browser handles the multipart
+boundary automatically.
+
+#### Interceptors
+
+Interceptors are passed at construction time and are immutable. They can transform requests, short-circuit responses,
+retry on failure, or modify responses. Different client instances can have independent interceptor stacks.
+
+#### Explicit Error Handling
+
+All requests return `IO<HttpError, T>`, explicitly modeling success and failure. Errors include HTTP status, response
+body, headers, and URL for full diagnostic context.
+
+### Usage
+
+**Creating a Client**
+```typescript
+import { HttpClient } from "@openstage/monadyssey-fetch";
+
+const api = new HttpClient({
+  baseUrl: "https://api.example.com",
+  interceptors: [authInterceptor],
+  defaultHeaders: { "Accept": "application/json" },
+  timeout: 5000,
+});
+```
+
+**GET Request**
+```typescript
+const result = await api.get<User>("/users/1").unsafeRun();
+```
+
+**POST Request with Body**
+```typescript
+await api.post<User>("/users", { name: "New User" })
+  .tap((user) => console.log(user))
+  .mapErr((error) => console.error(error))
+  .unsafeRun();
+```
+
+**File Upload with FormData**
+```typescript
+const formData = new FormData();
+formData.append("file", file);
+
+await api.post("/upload", formData).unsafeRun();
+```
+
+**Custom Request with `fetch`**
+```typescript
+await api.fetch<{ message: string }>("/custom", "OPTIONS", {
+  headers: { "X-Custom-Header": "value" },
+}).unsafeRun();
+```
+
+### Options
+
+| **Option**     | **Type**                                                    | **Description**                                                               |
+|----------------|-------------------------------------------------------------|-------------------------------------------------------------------------------|
+| `headers`     | `Record<string, string>`                                     | Custom headers. Merged with defaults, keys normalized to lowercase            |
+| `body`        | `any`                                                        | Request payload. Objects auto-JSON; FormData/Blob passed as-is                |
+| `responseType`| `"json"`, `"text"`, `"blob"`, `"arrayBuffer"`, `"formData"` | Expected response type. **Defaults to `"json"`**                              |
+| `credentials` | `"omit"`, `"same-origin"`, `"include"`                      | Credential policy. **Defaults to client setting (`"same-origin"`)**           |
+| `observe`     | `"body"` or `"response"`                                     | Return parsed body or full `Response`. **Defaults to `"body"`**               |
+| `transform`   | `(data: any) => A`                                           | Transform the response data                                                   |
+| `timeout`     | `number`                                                     | Per-request timeout in milliseconds. Overrides client-level timeout           |
+
+### Error Handling
+
+Errors are encapsulated in the `HttpError` type, which includes:
+
+* `status`: The HTTP status code (500 for network errors)
+* `message`: Formatted error message containing the URL, status, and raw message
+* `rawMessage`: The raw error description
+* `body`: The response body if available
+* `url`: The request URL
+* `headers`: The response headers if available
+
+### License
+
+This project is licensed under the MIT License.