jiren 1.1.1 → 1.1.5

package/README.md

@@ -6,12 +6,13 @@ Designed to be significantly faster than `fetch` and other Node/Bun HTTP clients
 ## Features
 
 - **Native Performance**: Written in Zig for memory safety and speed.
-- **Zero-Copy (Planned)**: Minimal overhead FFI.
-- **HTTP/1.1 & HTTP/3 (QUIC)**: Support for modern protocols.
+- **Anti-Bot Protection**: Bypass Cloudflare with curl-impersonate (Chrome TLS fingerprinting).
+- **HTTP/1.1, HTTP/2 & HTTP/3 (QUIC)**: Full support for modern protocols.
 - **Connection Pooling**: Reuse connections for maximum throughput.
-- **0-RTT Session Resumption**: Extremely fast subsequent requests.
-- **Smart Warmup**: Pre-warm connections to reduce latency.
+- **Mandatory Warmup**: Pre-warm connections for instant requests.
+- **Type-Safe URLs**: Define named endpoints with full TypeScript autocomplete.
 - **JSON & Text Helpers**: Easy response parsing.
+- **Automatic Gzip Decompression**: Handles compressed responses transparently.
 
 ## Installation
 
@@ -21,17 +22,25 @@ bun add jiren
 
 ## Usage
 
-### Basic GET
+### Basic Usage (Type-Safe URLs)
+
+**Warmup is now mandatory** - you must define URLs in the constructor:
 
 ```typescript
 import { JirenClient } from "jiren";
 
-const client = new JirenClient();
-const res = await client.get("https://example.com");
+const client = new JirenClient({
+  warmup: {
+    google: "https://www.google.com",
+    github: "https://api.github.com",
+    myapi: "https://api.myservice.com",
+  },
+});
 
+// TypeScript knows about 'google', 'github', 'myapi' - full autocomplete!
+const res = await client.url.google.get();
 console.log(res.status);
-const text = await res.text();
-console.log(text);
+const text = await res.body.text();
 ```
 
 ### JSON Response
@@ -42,38 +51,192 @@ interface User {
   name: string;
 }
 
-const res = await client.get<User>("https://api.example.com/user/1");
-const user = await res.json();
-console.log(user.name);
+const client = new JirenClient({
+  warmup: {
+    api: "https://api.example.com",
+  },
+});
+
+const res = await client.url.api.get<User>({
+  path: "/user/1",
+  responseType: "json",
+});
+console.log(res.name); // Fully typed!
 ```
 
-### Warmup / Prefetching
+### Anti-Bot Mode (NEW! �️)
+
+Enable curl-impersonate for sites with bot protection:
+
+```typescript
+const client = new JirenClient({
+  warmup: {
+    protected: "https://protected-site.com",
+  },
+});
+
+// Enable antibot mode for this request
+const res = await client.url.protected.get({
+  antibot: true, // Uses curl-impersonate with Chrome fingerprinting
+});
+```
 
-Warm up DNS and TLS handshakes to ensure subsequent requests are instant.
-You can do this in the constructor or via the `warmup` method.
+### POST, PUT, PATCH, DELETE
 
 ```typescript
-// Option 1: In constructor
 const client = new JirenClient({
-  warmup: ["https://google.com", "https://cloudflare.com"],
+  warmup: {
+    api: "https://api.myservice.com",
+  },
 });
 
-// Option 2: Explicit method call
-client.warmup(["https://example.org"]);
+// POST with body
+const created = await client.url.api.post(
+  JSON.stringify({ name: "New Item" }),
+  {
+    path: "/items",
+    headers: { "Content-Type": "application/json" },
+  }
+);
+
+// PUT, PATCH, DELETE
+await client.url.api.put(body, { path: "/items/1" });
+await client.url.api.patch(body, { path: "/items/1" });
+await client.url.api.delete(null, { path: "/items/1" });
+```
+
+### Response Helpers
+
+```typescript
+const res = await client.url.api.get({ path: "/data" });
+
+// Get as text
+const text = await res.body.text();
+
+// Get as JSON
+const json = await res.body.json();
+
+// Get as ArrayBuffer
+const buffer = await res.body.arrayBuffer();
+
+// Get as Blob
+const blob = await res.body.blob();
 
-// ... later, requests are instant
-const res = await client.get("https://google.com");
+// Or use responseType for automatic parsing
+const data = await client.url.api.get({
+  path: "/data",
+  responseType: "json", // Returns parsed JSON directly
+});
 ```
 
-## Benchmarks
+## Why Jiren?
+
+### Comparison with Other Clients
+
+| Feature              | **Jiren** | **Axios** | **ky** | **got** | **node-fetch** |
+| -------------------- | :-------: | :-------: | :----: | :-----: | :------------: |
+| Type-safe named URLs |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| Mandatory warmup     |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| HTTP/3 (QUIC)        |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| Anti-bot protection  |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| Native performance   |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+| Zero code generation |    ✅     |    ✅     |   ✅   |   ✅    |       ✅       |
+| Bun FFI optimized    |    ✅     |    ❌     |   ❌   |   ❌    |       ❌       |
+
+### What Makes Jiren Unique
+
+1. **🔥 Mandatory Warmup** - Pre-establishes connections at startup for instant requests
+2. **📝 Type-Safe URLs** - Full autocomplete without needing backend schemas or code generation
+3. **🚀 Native Speed** - Zig-powered core bypasses JavaScript overhead
+4. **🛡️ Anti-Bot Protection** - Bypass Cloudflare, TLS fingerprinting, and bot detection with curl-impersonate
+5. **⚡ HTTP/3 Support** - First-class QUIC support for modern protocols
+
+## Anti-Bot Protection
+
+The `antibot` option uses curl-impersonate to mimic Chrome's TLS fingerprint:
+
+- Bypass TLS fingerprinting protections (JA3/JA4) like Cloudflare
+- Chrome 120 browser impersonation
+- Proper header ordering and HTTP/2 settings
+- Automatic gzip decompression
+
+```typescript
+const res = await client.url.site.get({
+  antibot: true, // Enable for protected sites
+});
+```
+
+**Performance**: ~1-2s for first request, faster with connection reuse.
+
+## API Reference
+
+### `JirenClient`
+
+```typescript
+// Constructor options
+interface JirenClientOptions {
+  warmup: Record<string, string>; // Required! Map of key -> URL
+}
+
+// Create client (warmup is mandatory)
+const client = new JirenClient({
+  warmup: {
+    api: "https://api.example.com",
+    cdn: "https://cdn.example.com",
+  },
+});
+
+// Type-safe URL access
+client.url[key].get(options?)
+client.url[key].post(body?, options?)
+client.url[key].put(body?, options?)
+client.url[key].patch(body?, options?)
+client.url[key].delete(body?, options?)
+client.url[key].head(options?)
+client.url[key].options(options?)
+
+// Cleanup
+client.close()
+```
+
+### Request Options
+
+```typescript
+interface UrlRequestOptions {
+  path?: string; // Path to append to base URL
+  headers?: Record<string, string>;
+  maxRedirects?: number;
+  responseType?: "json" | "text" | "arraybuffer" | "blob";
+  antibot?: boolean; // Enable curl-impersonate (default: false)
+}
+```
+
+### Response Object
+
+```typescript
+interface JirenResponse<T> {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  ok: boolean;
+  body: {
+    text(): Promise<string>;
+    json<R = T>(): Promise<R>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob(): Promise<Blob>;
+  };
+}
+```
+
+## Performance
+
+Benchmark results:
+
+- **Bun fetch**: ~950-1780ms
+- **JirenClient**: ~480-1630ms
 
-**Jiren** delivers native performance by bypassing the JavaScript engine overhead for network I/O.
+JirenClient is often **faster than Bun's native fetch** thanks to optimized connection pooling and native Zig implementation.
 
-| Client            | Requests/sec  | Relative Speed |
-| ----------------- | ------------- | -------------- |
-| **Jiren**         | **1,550,000** | **1.0x**       |
-| Bun `fetch`       | 45,000        | 34x Slower     |
-| Node `http`       | 32,000        | 48x Slower     |
-| Python `requests` | 6,500         | 238x Slower    |
+## License
 
-> Benchmarks run on MacBook Pro M3 Max, localhost loopback.
+MIT

package/components/client.ts

@@ -1,23 +1,258 @@
 import { CString, toArrayBuffer, type Pointer } from "bun:ffi";
 import { lib } from "./native";
-import type { RequestOptions } from "./types";
+import type {
+  RequestOptions,
+  JirenResponse,
+  JirenResponseBody,
+  WarmupUrlConfig,
+  UrlRequestOptions,
+  UrlEndpoint,
+} from "./types";
 
-export interface JirenClientOptions {
+const STATUS_TEXT: Record<number, string> = {
+  200: "OK",
+  201: "Created",
+  204: "No Content",
+  301: "Moved Permanently",
+  302: "Found",
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+};
+
+/** Options for JirenClient constructor */
+export interface JirenClientOptions<
+  T extends readonly WarmupUrlConfig[] | Record<string, string> =
+    | readonly WarmupUrlConfig[]
+    | Record<string, string>
+> {
   /** URLs to warmup on client creation (pre-connect + handshake) */
-  warmup?: string[];
+  warmup?: string[] | T;
+
+  /** Enable benchmark mode (Force HTTP/2, disable probing) */
+  benchmark?: boolean;
 }
 
-export class JirenClient {
+/** Helper to extract keys from Warmup Config */
+export type ExtractWarmupKeys<
+  T extends readonly WarmupUrlConfig[] | Record<string, string>
+> = T extends readonly WarmupUrlConfig[]
+  ? T[number]["key"]
+  : T extends Record<string, string>
+  ? keyof T
+  : never;
+
+/** Type-safe URL accessor - maps keys to UrlEndpoint objects */
+export type UrlAccessor<
+  T extends readonly WarmupUrlConfig[] | Record<string, string>
+> = {
+  [K in ExtractWarmupKeys<T>]: UrlEndpoint;
+};
+
+/**
+ * Helper function to define warmup URLs with type inference.
+ * This eliminates the need for 'as const'.
+ *
+ * @example
+ * ```typescript
+ * const client = new JirenClient({
+ *   warmup: defineUrls([
+ *     { key: "google", url: "https://google.com" },
+ *   ])
+ * });
+ * // OR
+ * const client = new JirenClient({
+ *   warmup: {
+ *      google: "https://google.com"
+ *   }
+ * });
+ * ```
+ */
+export function defineUrls<const T extends readonly WarmupUrlConfig[]>(
+  urls: T
+): T {
+  return urls;
+}
+
+export class JirenClient<
+  T extends readonly WarmupUrlConfig[] | Record<string, string> =
+    | readonly WarmupUrlConfig[]
+    | Record<string, string>
+> {
   private ptr: Pointer | null;
+  private urlMap: Map<string, string> = new Map();
+
+  /** Type-safe URL accessor for warmed-up URLs */
+  public readonly url: UrlAccessor<T>;
 
-  constructor(options?: JirenClientOptions) {
+  constructor(options?: JirenClientOptions<T>) {
     this.ptr = lib.symbols.zclient_new();
     if (!this.ptr) throw new Error("Failed to create native client instance");
 
-    // Warmup connections immediately if URLs provided
-    if (options?.warmup && options.warmup.length > 0) {
-      this.warmup(options.warmup);
+    // Enable benchmark mode if requested
+    if (options?.benchmark) {
+      lib.symbols.zclient_set_benchmark_mode(this.ptr, true);
+    }
+
+    // Process warmup URLs
+    if (options?.warmup) {
+      const urls: string[] = [];
+      const warmup = options.warmup;
+
+      if (Array.isArray(warmup)) {
+        for (const item of warmup) {
+          if (typeof item === "string") {
+            urls.push(item);
+          } else {
+            // WarmupUrlConfig with key
+            const config = item as WarmupUrlConfig;
+            urls.push(config.url);
+            this.urlMap.set(config.key, config.url);
+          }
+        }
+      } else {
+        // Record<string, string>
+        for (const [key, url] of Object.entries(warmup)) {
+          urls.push(url as string);
+          this.urlMap.set(key, url as string);
+        }
+      }
+
+      if (urls.length > 0) {
+        this.warmup(urls);
+      }
     }
+
+    // Create proxy for type-safe URL access
+    this.url = this.createUrlAccessor();
+  }
+
+  /**
+   * Creates a proxy-based URL accessor for type-safe access to warmed-up URLs.
+   */
+  private createUrlAccessor(): UrlAccessor<T> {
+    const self = this;
+
+    return new Proxy({} as UrlAccessor<T>, {
+      get(_target, prop: string) {
+        const baseUrl = self.urlMap.get(prop);
+        if (!baseUrl) {
+          throw new Error(
+            `URL key "${prop}" not found. Available keys: ${Array.from(
+              self.urlMap.keys()
+            ).join(", ")}`
+          );
+        }
+
+        // Helper to build full URL with optional path
+        const buildUrl = (path?: string) =>
+          path
+            ? `${baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`
+            : baseUrl;
+
+        // Return a UrlEndpoint object with all HTTP methods
+        return {
+          get: async <R = any>(
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>("GET", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              responseType: options?.responseType,
+              antibot: options?.antibot,
+            });
+          },
+
+          post: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "POST",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          put: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "PUT",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          patch: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "PATCH",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          delete: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "DELETE",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          head: async (
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<any>> => {
+            return self.request("HEAD", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+            });
+          },
+
+          options: async (
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<any>> => {
+            return self.request("OPTIONS", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+            });
+          },
+        } as UrlEndpoint;
+      },
+    });
   }
 
   /**
@@ -58,27 +293,67 @@ export class JirenClient {
    * @param url - The URL to request
    * @param body - The body content string (optional)
    * @param options - Request options (headers, maxRedirects, etc.) or just headers map
-   * @returns Promise resolving to Response object
+   * @returns Promise resolving to Response object or parsed body
    */
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "json" }
+  ): Promise<T>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "text" }
+  ): Promise<string>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "arraybuffer" }
+  ): Promise<ArrayBuffer>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "blob" }
+  ): Promise<Blob>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions
+  ): Promise<JirenResponse<T>>;
   public async request<T = any>(
     method: string,
     url: string,
     body?: string | null,
     options?: RequestOptions | Record<string, string> | null
-  ) {
+  ): Promise<JirenResponse<T> | T | string | ArrayBuffer | Blob> {
     if (!this.ptr) throw new Error("Client is closed");
 
     // Normalize options
     let headers: Record<string, string> = {};
     let maxRedirects = 5; // Default
+    let responseType: RequestOptions["responseType"] | undefined;
+    let antibot = false; // Default
 
     if (options) {
-      if ("maxRedirects" in options || "headers" in options) {
+      if (
+        "maxRedirects" in options ||
+        "headers" in options ||
+        "responseType" in options ||
+        "method" in options || // Check for any RequestOptions specific key
+        "timeout" in options ||
+        "antibot" in options
+      ) {
         // It is RequestOptions
         const opts = options as RequestOptions;
         if (opts.headers) headers = opts.headers;
         if (opts.maxRedirects !== undefined) maxRedirects = opts.maxRedirects;
-        // Merge top-level unknown keys as headers if lenient? No, strict to types.
+        if (opts.responseType) responseType = opts.responseType;
+        if (opts.antibot !== undefined) antibot = opts.antibot;
       } else {
         // Assume it's just headers Record<string, string> for backward compatibility
         headers = options as Record<string, string>;
@@ -99,13 +374,52 @@ export class JirenClient {
         "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
       accept:
         "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
-      "accept-encoding": "gzip, deflate, br",
+      "accept-encoding": "gzip",
       "accept-language": "en-US,en;q=0.9",
+      "sec-ch-ua":
+        '"Not_A Brand";v="8", "Chromium";v="120", "Google Chrome";v="120"',
+      "sec-ch-ua-mobile": "?0",
+      "sec-ch-ua-platform": '"macOS"',
+      "sec-fetch-dest": "document",
+      "sec-fetch-mode": "navigate",
+      "sec-fetch-site": "none",
+      "sec-fetch-user": "?1",
+      "upgrade-insecure-requests": "1",
     };
 
     const finalHeaders = { ...defaultHeaders, ...headers };
 
-    const headerStr = Object.entries(finalHeaders)
+    // Enforce Chrome header order
+    const orderedHeaders: Record<string, string> = {};
+    const keys = [
+      "sec-ch-ua",
+      "sec-ch-ua-mobile",
+      "sec-ch-ua-platform",
+      "upgrade-insecure-requests",
+      "user-agent",
+      "accept",
+      "sec-fetch-site",
+      "sec-fetch-mode",
+      "sec-fetch-user",
+      "sec-fetch-dest",
+      "accept-encoding",
+      "accept-language",
+    ];
+
+    // Add priority headers in order
+    for (const key of keys) {
+      if (finalHeaders[key]) {
+        orderedHeaders[key] = finalHeaders[key];
+        delete finalHeaders[key];
+      }
+    }
+
+    // Add remaining custom headers
+    for (const [key, value] of Object.entries(finalHeaders)) {
+      orderedHeaders[key] = value;
+    }
+
+    const headerStr = Object.entries(orderedHeaders)
       .map(([k, v]) => `${k.toLowerCase()}: ${v}`)
       .join("\r\n");
 
@@ -119,60 +433,27 @@ export class JirenClient {
       urlBuffer,
       headersBuffer,
       bodyBuffer,
-      maxRedirects
+      maxRedirects,
+      antibot
     );
 
-    return this.parseResponse<T>(respPtr);
-  }
-
-  public async get<T = any>(
-    url: string,
-    options?: RequestOptions | Record<string, string>
-  ) {
-    return this.request<T>("GET", url, null, options);
-  }
-
-  public async post<T = any>(
-    url: string,
-    body: string,
-    options?: RequestOptions | Record<string, string>
-  ) {
-    return this.request<T>("POST", url, body, options);
-  }
-
-  public async put<T = any>(
-    url: string,
-    body: string,
-    options?: RequestOptions | Record<string, string>
-  ) {
-    return this.request<T>("PUT", url, body, options);
-  }
-
-  public async patch<T = any>(
-    url: string,
-    body: string,
-    options?: RequestOptions | Record<string, string>
-  ) {
-    return this.request<T>("PATCH", url, body, options);
-  }
-
-  public async delete<T = any>(
-    url: string,
-    body?: string,
-    options?: RequestOptions | Record<string, string>
-  ) {
-    return this.request<T>("DELETE", url, body || null, options);
-  }
+    const response = this.parseResponse<T>(respPtr, url);
 
-  public async head(url: string, headers?: Record<string, string>) {
-    return this.request("HEAD", url, null, headers);
-  }
+    // Auto-parse if requested
+    if (responseType) {
+      if (responseType === "json") return response.body.json();
+      if (responseType === "text") return response.body.text();
+      if (responseType === "arraybuffer") return response.body.arrayBuffer();
+      if (responseType === "blob") return response.body.blob();
+    }
 
-  public async options(url: string, headers?: Record<string, string>) {
-    return this.request("OPTIONS", url, null, headers);
+    return response;
   }
 
-  private parseResponse<T = any>(respPtr: Pointer | null) {
+  private parseResponse<T = any>(
+    respPtr: Pointer | null,
+    url: string
+  ): JirenResponse<T> {
     if (!respPtr)
       throw new Error("Native request failed (returned null pointer)");
 
@@ -181,20 +462,178 @@ export class JirenClient {
       const len = Number(lib.symbols.zclient_response_body_len(respPtr));
       const bodyPtr = lib.symbols.zclient_response_body(respPtr);
 
-      let bodyString = "";
+      const headersLen = Number(
+        lib.symbols.zclient_response_headers_len(respPtr)
+      );
+      let headersObj: Record<string, string> | NativeHeaders = {};
+
+      if (headersLen > 0) {
+        const rawHeadersPtr = lib.symbols.zclient_response_headers(respPtr);
+        if (rawHeadersPtr) {
+          // Copy headers to JS memory
+          // We need to copy because respPtr will be freed
+          const rawSrc = toArrayBuffer(rawHeadersPtr, 0, headersLen);
+          const raw = new Uint8Array(rawSrc.slice(0)); // Explicit copy
+
+          headersObj = new NativeHeaders(raw);
+        }
+      }
+
+      // Proxy for backward compatibility
+      const headersProxy = new Proxy(
+        headersObj instanceof NativeHeaders ? headersObj : {},
+        {
+          get(target, prop) {
+            if (target instanceof NativeHeaders && typeof prop === "string") {
+              if (prop === "toJSON") return () => target.toJSON();
+
+              // Try to get from native headers
+              const val = target.get(prop);
+              if (val !== null) return val;
+            }
+            return Reflect.get(target, prop);
+          },
+        }
+      ) as unknown as Record<string, string>; // Lie to TS
+
+      let buffer: ArrayBuffer | Buffer = new ArrayBuffer(0);
       if (len > 0 && bodyPtr) {
-        const buffer = toArrayBuffer(bodyPtr, 0, len);
-        bodyString = new TextDecoder().decode(buffer);
+        // Create a copy of the buffer because the native response is freed immediately after
+        buffer = toArrayBuffer(bodyPtr, 0, len).slice(0);
       }
 
+      let bodyUsed = false;
+      const consumeBody = () => {
+        if (bodyUsed) {
+        }
+        bodyUsed = true;
+      };
+
+      const bodyObj: JirenResponseBody<T> = {
+        bodyUsed: false,
+        arrayBuffer: async () => {
+          consumeBody();
+          if (Buffer.isBuffer(buffer)) {
+            const buf = buffer as Buffer;
+            return buf.buffer.slice(
+              buf.byteOffset,
+              buf.byteOffset + buf.byteLength
+            ) as ArrayBuffer;
+          }
+          return buffer as ArrayBuffer;
+        },
+        blob: async () => {
+          consumeBody();
+          return new Blob([buffer]);
+        },
+        text: async () => {
+          consumeBody();
+          return new TextDecoder().decode(buffer);
+        },
+        json: async <R = T>(): Promise<R> => {
+          consumeBody();
+          const text = new TextDecoder().decode(buffer);
+          return JSON.parse(text);
+        },
+      };
+
+      // Update bodyUsed getter to reflect local variable
+      Object.defineProperty(bodyObj, "bodyUsed", {
+        get: () => bodyUsed,
+      });
+
       return {
+        url,
         status,
-        body: bodyString,
-        text: async () => bodyString,
-        json: async (): Promise<T> => JSON.parse(bodyString),
-      };
+        statusText: STATUS_TEXT[status] || "",
+        headers: headersProxy,
+        ok: status >= 200 && status < 300,
+        redirected: false,
+        type: "basic",
+        body: bodyObj,
+      } as JirenResponse<T>;
     } finally {
       lib.symbols.zclient_response_free(respPtr);
     }
   }
 }
+
+class NativeHeaders {
+  private raw: Uint8Array;
+  private len: number;
+  private decoder = new TextDecoder();
+  private cache = new Map<string, string>();
+  // We need a pointer to the raw buffer for FFI calls.
+  // Since we can't easily rely on ptr(this.raw) being stable if we stored it,
+  // we will pass this.raw to the FFI call directly each time.
+
+  constructor(raw: Uint8Array) {
+    this.raw = raw;
+    this.len = raw.byteLength;
+  }
+
+  get(name: string): string | null {
+    const target = name.toLowerCase();
+    if (this.cache.has(target)) return this.cache.get(target)!;
+
+    const keyBuf = Buffer.from(target + "\0");
+
+    // Debug log
+    // Pass the raw buffer directly. Bun handles the pointer.
+    const resPtr = lib.symbols.z_find_header_value(
+      this.raw as any,
+      this.len,
+      keyBuf
+    );
+
+    if (!resPtr) return null;
+
+    try {
+      // ZHeaderValue: { value_ptr: pointer, value_len: size_t }
+      // Assuming 64-bit architecture, pointers and size_t are 8 bytes.
+      // Struct size = 16 bytes.
+      const view = new DataView(toArrayBuffer(resPtr, 0, 16));
+      const valPtr = view.getBigUint64(0, true);
+      const valLen = Number(view.getBigUint64(8, true));
+
+      if (valLen === 0) {
+        this.cache.set(target, "");
+        return "";
+      }
+
+      // Convert valPtr to ArrayBuffer
+      // Note: valPtr points inside this.raw, but toArrayBuffer(ptr) creates a view on that memory.
+      const valBytes = toArrayBuffer(Number(valPtr) as any, 0, valLen);
+      const val = this.decoder.decode(valBytes);
+
+      this.cache.set(target, val);
+      return val;
+    } finally {
+      lib.symbols.zclient_header_value_free(resPtr);
+    }
+  }
+
+  // Fallback for when full object is needed (e.g. debugging)
+  // This is expensive as it reparses everything using the old offset method
+  // BUT we don't have the offset method easily available on the raw buffer unless we expose a new one?
+  // Wait, `zclient_response_parse_header_offsets` takes `Response*`.
+  // We don't have Response* anymore.
+  // We need `z_parse_header_offsets_from_raw(ptr, len)`.
+  // Or just parse in JS since we have the full buffer?
+  // Actually, we can just do a JS parser since we have the buffer.
+  // It's a fallback anyway.
+  toJSON(): Record<string, string> {
+    const obj: Record<string, string> = {};
+    const text = this.decoder.decode(this.raw);
+    const lines = text.split("\r\n");
+    for (const line of lines) {
+      if (!line) continue;
+      const colon = line.indexOf(":");
+      if (colon === -1) continue;
+      const key = line.substring(0, colon).trim().toLowerCase();
+      const val = line.substring(colon + 1).trim();
+      obj[key] = val;
+    }
+    return obj;
+  }
+}

package/components/index.ts

@@ -5,9 +5,19 @@
  */
 
 // Main client
-export { JirenClient, type JirenClientOptions } from "./client";
+export {
+  JirenClient,
+  type JirenClientOptions,
+  type UrlAccessor,
+} from "./client";
 
 // Types
-export type { JirenHttpConfig, ParsedUrl } from "../types/index";
+export type {
+  JirenHttpConfig,
+  ParsedUrl,
+  WarmupUrlConfig,
+  UrlRequestOptions,
+  UrlEndpoint,
+} from "./types";
 
 // Remove broken exports

package/components/native.ts

@@ -29,6 +29,7 @@ export const ffiDef = {
       FFIType.cstring,
       FFIType.cstring,
       FFIType.u8,
+      FFIType.bool,
     ],
     returns: FFIType.ptr,
   },
@@ -56,10 +57,30 @@ export const ffiDef = {
     args: [FFIType.ptr],
     returns: FFIType.u64,
   },
+  zclient_response_parse_header_offsets: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
+  zclient_header_offsets_free: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  z_find_header_value: {
+    args: [FFIType.ptr, FFIType.u64, FFIType.cstring],
+    returns: FFIType.ptr,
+  },
+  zclient_header_value_free: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
   zclient_response_free: {
     args: [FFIType.ptr],
     returns: FFIType.void,
   },
+  zclient_set_benchmark_mode: {
+    args: [FFIType.ptr, FFIType.bool],
+    returns: FFIType.void,
+  },
 } as const;
 
 export const lib = dlopen(libPath, ffiDef);

package/components/types.ts

@@ -34,16 +34,44 @@ export interface RequestOptions {
   timeout?: number;
   /** Maximum number of redirects to follow */
   maxRedirects?: number;
+  /** Automatically parse response body */
+  responseType?: "json" | "text" | "arraybuffer" | "blob";
+  /** Enable anti-bot protection (using curl-impersonate) */
+  antibot?: boolean;
+}
+
+/** HTTP Response Body Wrapper */
+export interface JirenResponseBody<T = any> {
+  /** Get response as JSON */
+  json: <R = T>() => Promise<R>;
+  /** Get response as text */
+  text: () => Promise<string>;
+  /** Get response as ArrayBuffer */
+  arrayBuffer: () => Promise<ArrayBuffer>;
+  /** Get response as Blob */
+  blob: () => Promise<Blob>;
+  /** Whether the body has been used */
+  bodyUsed: boolean;
 }
 
 /** HTTP Response */
-export interface HttpResponse {
+export interface JirenResponse<T = any> {
   /** HTTP status code */
   status: number;
-  /** Response body as string */
-  body: string;
+  /** Response body object */
+  body: JirenResponseBody<T>;
   /** Response headers */
-  headers?: Record<string, string>;
+  headers: Record<string, string>;
+  /** Whether the request was successful (status 200-299) */
+  ok: boolean;
+  /** The URL of the response */
+  url: string;
+  /** The status message corresponding to the status code */
+  statusText: string;
+  /** Whether the response was redirected */
+  redirected: boolean;
+  /** The type of the response */
+  type: "basic" | "cors" | "default" | "error" | "opaque" | "opaqueredirect";
 }
 
 /** Configuration for JirenHttpClient */
@@ -61,3 +89,87 @@ export interface ParsedUrl {
   port: number;
   path: string;
 }
+
+/** Warmup URL with a key for type-safe access */
+export interface WarmupUrlConfig {
+  /** Unique key to access this URL via client.url[key] */
+  key: string;
+  /** The URL to warmup */
+  url: string;
+}
+
+/** Options for URL endpoint requests */
+export interface UrlRequestOptions {
+  /** Request headers */
+  headers?: Record<string, string>;
+  /** Path to append to the base URL */
+  path?: string;
+  /** Maximum number of redirects to follow */
+  maxRedirects?: number;
+  /** Automatically parse response body */
+  responseType?: "json" | "text" | "arraybuffer" | "blob";
+  /** Enable anti-bot protection (using curl-impersonate) */
+  antibot?: boolean;
+}
+
+/** Interface for a URL endpoint with HTTP method helpers */
+export interface UrlEndpoint {
+  /** GET request */
+  get<T = any>(options?: UrlRequestOptions): Promise<JirenResponse<T>>;
+  get<T = any>(
+    options?: UrlRequestOptions & { responseType: "json" }
+  ): Promise<T>;
+  get<T = any>(
+    options?: UrlRequestOptions & { responseType: "text" }
+  ): Promise<string>;
+
+  /** POST request */
+  post<T = any>(
+    body?: string | null,
+    options?: UrlRequestOptions
+  ): Promise<JirenResponse<T>>;
+  post<T = any>(
+    body?: string | null,
+    options?: UrlRequestOptions & { responseType: "json" }
+  ): Promise<T>;
+
+  /** PUT request */
+  put<T = any>(
+    body?: string | null,
+    options?: UrlRequestOptions
+  ): Promise<JirenResponse<T>>;
+  put<T = any>(
+    body?: string | null,
+    options?: UrlRequestOptions & { responseType: "json" }
+  ): Promise<T>;
+
+  /** PATCH request */
+  patch<T = any>(
+    body?: string | null,
+    options?: UrlRequestOptions
+  ): Promise<JirenResponse<T>>;
+  patch<T = any>(
+    body?: string | null,
+    options?: UrlRequestOptions & { responseType: "json" }
+  ): Promise<T>;
+
+  /** DELETE request */
+  delete<T = any>(
+    body?: string | null,
+    options?: UrlRequestOptions
+  ): Promise<JirenResponse<T>>;
+  delete<T = any>(
+    body?: string | null,
+    options?: UrlRequestOptions & { responseType: "json" }
+  ): Promise<T>;
+
+  /** HEAD request */
+  head(options?: UrlRequestOptions): Promise<JirenResponse<any>>;
+
+  /** OPTIONS request */
+  options(options?: UrlRequestOptions): Promise<JirenResponse<any>>;
+}
+
+/** Type helper to extract keys from warmup config array */
+export type ExtractWarmupKeys<T extends readonly WarmupUrlConfig[]> =
+  T[number]["key"];

package/components/worker.ts

@@ -75,12 +75,17 @@ if (parentPort) {
           bodyBuffer = Buffer.from(bodyStr + "\0");
         }
 
+        const maxRedirects = options.maxRedirects ?? 5;
+        const antibot = options.antibot ?? false;
+
         const respPtr = lib.symbols.zclient_request(
           ptr,
           methodBuffer,
           urlBuffer,
           headersBuffer,
-          bodyBuffer
+          bodyBuffer,
+          maxRedirects,
+          antibot
         );
 
         // Parse Response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiren",
-  "version": "1.1.1",
+  "version": "1.1.5",
   "author": "",
   "main": "index.ts",
   "module": "index.ts",

package/types/index.ts

@@ -33,6 +33,12 @@ export interface RequestOptions {
   body?: string | object;
   /** Request timeout in milliseconds */
   timeout?: number;
+  /** Maximum number of redirects to follow */
+  maxRedirects?: number;
+  /** Automatically parse response body */
+  responseType?: "json" | "text" | "arraybuffer" | "blob";
+  /** Enable anti-bot protection (using curl-impersonate) */
+  antibot?: boolean;
 }
 
 /** HTTP Response */