jiren 1.4.0 → 1.5.0

package/README.md

@@ -46,6 +46,8 @@ console.log(users);
 - [Basic Usage](#basic-usage)
 - [Response Caching](#response-caching)
 - [Anti-Bot Protection](#anti-bot-protection)
+- [Request Interceptors](#request-interceptors)
+- [Metrics & Observability](#metrics--observability)
 - [Advanced Features](#advanced-features)
 - [Performance](#performance)
 - [API Reference](#api-reference)
@@ -225,13 +227,12 @@ Bypass Cloudflare and other bot protection using Chrome TLS fingerprinting:
 const client = new JirenClient({
   warmup: {
     protected: "https://cloudflare-protected-site.com",
+    antibot: true,
   },
 });
 
 // Enable anti-bot mode for this request
-const response = await client.url.protected.get({
-  antibot: true, // Uses curl-impersonate with Chrome 120 fingerprint
-});
+const response = await client.url.protected.get();
 ```
 
 **How it works:**
@@ -242,6 +243,222 @@ const response = await client.url.protected.get({
 
 ---
 
+## Request Interceptors
+
+Add middleware to intercept requests and responses for logging, auth injection, and more:
+
+### Basic Interceptors
+
+```typescript
+const client = new JirenClient({
+  warmup: { api: "https://api.example.com" },
+  interceptors: {
+    // Modify requests before sending
+    request: [
+      (ctx) => ({
+        ...ctx,
+        headers: { ...ctx.headers, Authorization: `Bearer ${getToken()}` },
+      }),
+    ],
+    // Transform responses after receiving
+    response: [
+      (ctx) => {
+        console.log(`[${ctx.response.status}] ${ctx.request.url}`);
+        return ctx;
+      },
+    ],
+    // Handle errors
+    error: [(err, ctx) => console.error(`Failed: ${ctx.url}`, err)],
+  },
+});
+```
+
+### Dynamic Interceptors with `use()`
+
+```typescript
+// Add interceptors after client creation
+client.use({
+  request: [
+    (ctx) => ({ ...ctx, headers: { ...ctx.headers, "X-Custom": "value" } }),
+  ],
+});
+```
+
+### Interceptor Types
+
+| Type       | Purpose                                          | Context                          |
+| ---------- | ------------------------------------------------ | -------------------------------- |
+| `request`  | Modify method, URL, headers, body before sending | `{ method, url, headers, body }` |
+| `response` | Transform response after receiving               | `{ request, response }`          |
+| `error`    | Handle errors centrally                          | `(error, requestContext)`        |
+
+---
+
+## Metrics & Observability
+
+Track performance, cache efficiency, and request statistics with built-in metrics collection:
+
+### Basic Metrics
+
+```typescript
+const client = new JirenClient({
+  warmup: {
+    api: {
+      url: "https://api.example.com",
+      cache: true,
+    },
+  },
+});
+
+// Make some requests
+await client.url.api.get({ path: "/users" });
+await client.url.api.get({ path: "/users" }); // Cache hit
+
+// Get endpoint metrics
+const metrics = client.metrics.get("api");
+console.log(metrics);
+/*
+{
+  endpoint: "api",
+  requests: {
+    total: 2,
+    success: 2,
+    failed: 0
+  },
+  statusCodes: { 200: 2 },
+  timing: {
+    avgMs: 50.5,
+    minMs: 0.01,
+    maxMs: 101,
+    p50Ms: 50.5,
+    p95Ms: 101,
+    p99Ms: 101
+  },
+  cache: {
+    l1Hits: 1,
+    l1Misses: 1,
+    l2Hits: 0,
+    l2Misses: 1,
+    hitRate: "50.00%"
+  },
+  deduplication: {
+    hits: 0,
+    misses: 2,
+    hitRate: "0.00%"
+  },
+  bytes: {
+    sent: 0,
+    received: 0
+  },
+  errors: {},
+  lastRequestAt: 1234567890000
+}
+*/
+```
+
+### Global Metrics
+
+```typescript
+// Get aggregated metrics across all endpoints
+const global = client.metrics.getGlobal();
+console.log(global);
+/*
+{
+  totalRequests: 8,
+  totalSuccess: 8,
+  totalFailed: 0,
+  avgResponseTimeMs: 125.5,
+  totalBytesSent: 1024,
+  totalBytesReceived: 4096,
+  overallCacheHitRate: "62.50%",
+  overallDeduplicationRate: "25.00%",
+  endpoints: 2,
+  uptime: 60000
+}
+*/
+```
+
+### All Endpoints
+
+```typescript
+// Get metrics for all endpoints
+const allMetrics = client.metrics.getAll();
+for (const [endpoint, metrics] of Object.entries(allMetrics)) {
+  console.log(`${endpoint}: ${metrics.cache.hitRate} cache hit rate`);
+}
+```
+
+### Export Metrics
+
+```typescript
+// Export all metrics as JSON
+const json = client.metrics.export();
+console.log(json); // Pretty-printed JSON string
+
+// Save to file or send to monitoring service
+await Bun.write("metrics.json", json);
+```
+
+### Reset Metrics
+
+```typescript
+// Reset specific endpoint
+client.metrics.reset("api");
+
+// Reset all metrics
+client.metrics.reset();
+```
+
+### Tracked Metrics
+
+| Category     | Metrics                                                    |
+| ------------ | ---------------------------------------------------------- |
+| **Requests** | Total, success, failed, status code distribution           |
+| **Timing**   | Average, min, max, P50, P95, P99 response times            |
+| **Cache**    | L1/L2 hits & misses, overall hit rate                      |
+| **Dedupe**   | Deduplication hits/misses for identical in-flight requests |
+| **Bytes**    | Total sent/received                                        |
+| **Errors**   | Error counts by type                                       |
+| **Other**    | Last request timestamp, client uptime                      |
+
+### Use Cases
+
+**Performance Monitoring:**
+
+```typescript
+// Track P99 latency
+setInterval(() => {
+  const metrics = client.metrics.getGlobal();
+  if (metrics.avgResponseTimeMs > 1000) {
+    console.warn("High latency detected!");
+  }
+}, 60000);
+```
+
+**Cache Optimization:**
+
+```typescript
+// Monitor cache effectiveness
+const metrics = client.metrics.get("api");
+console.log(`Cache hit rate: ${metrics.cache.hitRate}`);
+if (parseFloat(metrics.cache.hitRate) < 50) {
+  console.log("Consider increasing cache TTL");
+}
+```
+
+**Debugging:**
+
+```typescript
+// Export metrics for debugging
+if (process.env.DEBUG) {
+  process.on("exit", () => {
+    console.log(client.metrics.export());
+  });
+}
+```
+
+---
+
 ## Advanced Features
 
 ### TypeScript Generics