@aryanbansal-launch/edge-utils 0.1.9 → 0.1.11

package/bin/launch-help.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  dim: '\x1b[2m'
+};
+
+console.log(`
+${colors.bright}${colors.cyan}╔════════════════════════════════════════════════════════════════════╗
+║     🚀 Launch Edge Utils - Complete Reference Guide              ║
+╚════════════════════════════════════════════════════════════════════╝${colors.reset}
+
+${colors.bright}${colors.yellow}📦 AVAILABLE METHODS${colors.reset}
+${colors.dim}────────────────────────────────────────────────────────────────────${colors.reset}
+
+${colors.bright}${colors.green}1. Security & Access Control${colors.reset}
+
+  ${colors.cyan}blockAICrawlers(request, bots?)${colors.reset}
+    Block AI crawlers and bots from accessing your site
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+      - bots: string[] (optional) - Custom bot list
+    ${colors.dim}Default Blocked Bots:${colors.reset}
+      claudebot, gptbot, googlebot, bingbot, ahrefsbot,
+      yandexbot, semrushbot, mj12bot, facebookexternalhit, twitterbot
+    ${colors.dim}Returns:${colors.reset} Response | null
+    ${colors.dim}Example:${colors.reset}
+      const response = blockAICrawlers(request);
+      if (response) return response;
+
+  ${colors.cyan}blockDefaultDomains(request, options?)${colors.reset}
+    Block access via default Launch domains (*.contentstackapps.com)
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+      - options: { domainToBlock?: string }
+    ${colors.dim}Returns:${colors.reset} Response | null
+    ${colors.dim}Example:${colors.reset}
+      const response = blockDefaultDomains(request);
+      if (response) return response;
+
+  ${colors.cyan}ipAccessControl(request, options)${colors.reset}
+    Whitelist or blacklist IPs at the edge
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+      - options: { allow?: string[], deny?: string[] }
+    ${colors.dim}Returns:${colors.reset} Response | null
+    ${colors.dim}Example:${colors.reset}
+      const response = ipAccessControl(request, {
+        allow: ["203.0.113.10", "198.51.100.5"]
+      });
+      if (response) return response;
+
+  ${colors.cyan}protectWithBasicAuth(request, options)${colors.reset}
+    Add Basic Authentication to protect staging/dev environments
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+      - options: {
+          hostnameIncludes: string,
+          username: string,
+          password: string,
+          realm?: string
+        }
+    ${colors.dim}Returns:${colors.reset} Promise<Response> | null
+    ${colors.dim}Example:${colors.reset}
+      const auth = await protectWithBasicAuth(request, {
+        hostnameIncludes: "staging.myapp.com",
+        username: "admin",
+        password: "securepass123"
+      });
+      if (auth && auth.status === 401) return auth;
+
+${colors.bright}${colors.green}2. Routing & Redirects${colors.reset}
+
+  ${colors.cyan}redirectIfMatch(request, options)${colors.reset}
+    Conditional redirects based on path and method
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+      - options: {
+          path: string,
+          method?: string,
+          to: string,
+          status?: number
+        }
+    ${colors.dim}Returns:${colors.reset} Response | null
+    ${colors.dim}Example:${colors.reset}
+      const redirect = redirectIfMatch(request, {
+        path: "/old-page",
+        to: "/new-page",
+        status: 301
+      });
+      if (redirect) return redirect;
+
+${colors.bright}${colors.green}3. Next.js Optimization${colors.reset}
+
+  ${colors.cyan}handleNextJS_RSC(request, options)${colors.reset}
+    Fix Next.js React Server Components header issues
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+      - options: { affectedPaths: string[] }
+    ${colors.dim}Returns:${colors.reset} Promise<Response> | null
+    ${colors.dim}Example:${colors.reset}
+      const rsc = await handleNextJS_RSC(request, {
+        affectedPaths: ["/shop", "/about", "/products"]
+      });
+      if (rsc) return rsc;
+
+${colors.bright}${colors.green}4. Geo-Location${colors.reset}
+
+  ${colors.cyan}getGeoHeaders(request)${colors.reset}
+    Extract geo-location data from Launch headers
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+    ${colors.dim}Returns:${colors.reset} {
+      country: string | null,
+      region: string | null,
+      city: string | null,
+      latitude: string | null,
+      longitude: string | null
+    }
+    ${colors.dim}Example:${colors.reset}
+      const geo = getGeoHeaders(request);
+      if (geo.country === "US") {
+        // Custom logic for US visitors
+      }
+
+${colors.bright}${colors.green}5. Response Utilities${colors.reset}
+
+  ${colors.cyan}jsonResponse(body, init?)${colors.reset}
+    Create JSON responses easily
+    ${colors.dim}Parameters:${colors.reset}
+      - body: Record<string, unknown>
+      - init: ResponseInit (optional)
+    ${colors.dim}Returns:${colors.reset} Response
+    ${colors.dim}Example:${colors.reset}
+      return jsonResponse({ status: "ok", data: [...] });
+
+  ${colors.cyan}passThrough(request)${colors.reset}
+    Forward request to origin server
+    ${colors.dim}Parameters:${colors.reset}
+      - request: Request object
+    ${colors.dim}Returns:${colors.reset} Promise<Response>
+    ${colors.dim}Example:${colors.reset}
+      return passThrough(request);
+
+${colors.bright}${colors.green}6. Configuration${colors.reset}
+
+  ${colors.cyan}generateLaunchConfig(options)${colors.reset}
+    Generate launch.json configuration programmatically
+    ${colors.dim}Parameters:${colors.reset}
+      - options: {
+          redirects?: LaunchRedirect[],
+          rewrites?: LaunchRewrite[],
+          cache?: { cachePriming?: { urls: string[] } }
+        }
+    ${colors.dim}Returns:${colors.reset} LaunchConfig
+    ${colors.dim}Example:${colors.reset}
+      const config = generateLaunchConfig({
+        redirects: [{ source: "/old", destination: "/new", statusCode: 301 }],
+        cache: { cachePriming: { urls: ["/", "/about"] } }
+      });
+
+${colors.bright}${colors.yellow}🛠️  CLI COMMANDS${colors.reset}
+${colors.dim}────────────────────────────────────────────────────────────────────${colors.reset}
+
+  ${colors.cyan}npx create-launch-edge${colors.reset}
+    Initialize edge functions with boilerplate code
+    Creates: functions/[proxy].edge.js
+
+  ${colors.cyan}npx launch-config${colors.reset}
+    Interactive CLI to manage launch.json
+    Configure: redirects, rewrites, cache priming
+
+  ${colors.cyan}npx launch-help${colors.reset}
+    Display this help guide
+
+${colors.bright}${colors.yellow}📚 QUICK LINKS${colors.reset}
+${colors.dim}────────────────────────────────────────────────────────────────────${colors.reset}
+
+  ${colors.blue}Documentation:${colors.reset} https://github.com/AryanBansal-launch/launch-edge-utils
+  ${colors.blue}NPM Package:${colors.reset}   https://www.npmjs.com/package/@aryanbansal-launch/edge-utils
+  ${colors.blue}Launch Docs:${colors.reset}   https://www.contentstack.com/docs/developers/launch
+
+${colors.dim}────────────────────────────────────────────────────────────────────${colors.reset}
+`);
+

package/dist/ai/gemini.js

@@ -0,0 +1,153 @@
+/**
+ * Generates a complete Gemini AI Chatbot widget script to be injected at the Edge.
+ */
+export function getGeminiChatbotScript(options) {
+    const { apiKey, botName = "Gemini Assistant", welcomeMessage = "Hi! How can I help you today?", primaryColor = "#1a73e8", } = options;
+    return `
+<script>
+(function() {
+  // Create styles
+  const style = document.createElement('style');
+  style.textContent = \`
+    #gemini-chat-widget {
+      position: fixed;
+      bottom: 20px;
+      right: 20px;
+      z-index: 9999;
+      font-family: sans-serif;
+    }
+    #gemini-chat-button {
+      width: 60px;
+      height: 60px;
+      border-radius: 50%;
+      background-color: ${primaryColor};
+      color: white;
+      border: none;
+      cursor: pointer;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 24px;
+    }
+    #gemini-chat-window {
+      display: none;
+      width: 350px;
+      height: 500px;
+      background: white;
+      border-radius: 12px;
+      box-shadow: 0 8px 24px rgba(0,0,0,0.2);
+      flex-direction: column;
+      overflow: hidden;
+      margin-bottom: 15px;
+    }
+    #gemini-chat-header {
+      padding: 15px;
+      background: ${primaryColor};
+      color: white;
+      font-weight: bold;
+      display: flex;
+      justify-content: space-between;
+    }
+    #gemini-chat-messages {
+      flex: 1;
+      padding: 15px;
+      overflow-y: auto;
+      background: #f7f7f7;
+    }
+    .gemini-msg {
+      margin-bottom: 10px;
+      padding: 8px 12px;
+      border-radius: 8px;
+      max-width: 80%;
+      word-wrap: break-word;
+    }
+    .gemini-msg-bot { background: white; align-self: flex-start; border: 1px solid #eee; }
+    .gemini-msg-user { background: ${primaryColor}; color: white; align-self: flex-end; margin-left: auto; }
+    #gemini-chat-input-area {
+      padding: 10px;
+      border-top: 1px solid #eee;
+      display: flex;
+    }
+    #gemini-chat-input {
+      flex: 1;
+      border: 1px solid #ddd;
+      padding: 8px;
+      border-radius: 4px;
+      outline: none;
+    }
+  \`;
+  document.head.appendChild(style);
+
+  // Create HTML
+  const container = document.createElement('div');
+  container.id = 'gemini-chat-widget';
+  container.innerHTML = \`
+    <div id="gemini-chat-window">
+      <div id="gemini-chat-header">
+        <span>${botName}</span>
+        <button onclick="document.getElementById('gemini-chat-window').style.display='none'" style="background:none; border:none; color:white; cursor:pointer;">×</button>
+      </div>
+      <div id="gemini-chat-messages">
+        <div class="gemini-msg gemini-msg-bot">${welcomeMessage}</div>
+      </div>
+      <div id="gemini-chat-input-area">
+        <input type="text" id="gemini-chat-input" placeholder="Type a message...">
+      </div>
+    </div>
+    <button id="gemini-chat-button">💬</button>
+  \`;
+  document.body.appendChild(container);
+
+  const btn = document.getElementById('gemini-chat-button');
+  const win = document.getElementById('gemini-chat-window');
+  const input = document.getElementById('gemini-chat-input');
+  const msgContainer = document.getElementById('gemini-chat-messages');
+
+  btn.onclick = () => {
+    win.style.display = win.style.display === 'flex' ? 'none' : 'flex';
+    if (win.style.display === 'flex') input.focus();
+  };
+
+  async function sendMessage() {
+    const text = input.value.trim();
+    if (!text) return;
+
+    input.value = '';
+    appendMessage('user', text);
+
+    const loadingMsg = appendMessage('bot', '...');
+
+    try {
+      const response = await fetch('https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=${apiKey}', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          contents: [{ parts: [{ text }] }]
+        })
+      });
+      const data = await response.json();
+      const botReply = data.candidates[0].content.parts[0].text;
+      loadingMsg.textContent = botReply;
+    } catch (e) {
+      loadingMsg.textContent = 'Sorry, I am having trouble connecting.';
+    }
+    msgContainer.scrollTop = msgContainer.scrollHeight;
+  }
+
+  function appendMessage(role, text) {
+    const div = document.createElement('div');
+    div.className = 'gemini-msg gemini-msg-' + role;
+    div.textContent = text;
+    msgContainer.appendChild(div);
+    msgContainer.scrollTop = msgContainer.scrollHeight;
+    return div;
+  }
+
+  input.onkeypress = (e) => { if (e.key === 'Enter') sendMessage(); };
+})();
+</script>
+  \`;
+}
+`;
+}

package/dist/utils/inject.js

@@ -0,0 +1,45 @@
+/**
+ * Utility to inject HTML/scripts into a Response body using TransformStream.
+ * This is high-performance as it streams the modification without loading the full body into memory.
+ */
+class HTMLRewriterStream extends TransformStream {
+    constructor(contentToInject, position = 'before-body-end') {
+        const encoder = new TextEncoder();
+        const decoder = new TextDecoder();
+        super({
+            transform(chunk, controller) {
+                let html = decoder.decode(chunk);
+                if (position === 'before-body-end' && html.includes('</body>')) {
+                    html = html.replace('</body>', `${contentToInject}</body>`);
+                }
+                else if (position === 'after-head-start' && html.includes('<head>')) {
+                    html = html.replace('<head>', `<head>${contentToInject}`);
+                }
+                controller.enqueue(encoder.encode(html));
+            },
+        });
+    }
+}
+/**
+ * Injects a script or HTML snippet into a Response.
+ * @param response The original Response object
+ * @param options Injection options
+ */
+export async function injectScript(response, options) {
+    const contentType = response.headers.get('content-type');
+    // Only inject into HTML responses
+    if (!contentType || !contentType.includes('text/html')) {
+        return response;
+    }
+    const contentToInject = options.scriptUrl
+        ? `<script src="${options.scriptUrl}" async defer></script>`
+        : (options.script || '');
+    if (!contentToInject)
+        return response;
+    const rewriter = new HTMLRewriterStream(contentToInject, options.position);
+    return new Response(response.body?.pipeThrough(rewriter), {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryanbansal-launch/edge-utils",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -13,8 +13,9 @@
   },
   "main": "dist/index.js",
   "bin": {
-    "create-launch-edge": "./bin/launch-init.js",
-    "launch-config": "./bin/launch-config.js"
+    "create-launch-edge": "bin/launch-init.js",
+    "launch-config": "bin/launch-config.js",
+    "launch-help": "bin/launch-help.js"
   },
   "exports": {
     ".": "./dist/index.js"
@@ -24,6 +25,20 @@
     "bin"
   ],
   "scripts": {
-    "build": "tsc"
-  }
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "contentstack",
+    "launch",
+    "edge-functions",
+    "edge",
+    "middleware",
+    "security",
+    "nextjs",
+    "redirect",
+    "geo-location",
+    "basic-auth",
+    "ip-access"
+  ]
 }

package/readme.md

@@ -7,47 +7,73 @@ A comprehensive toolkit for [Contentstack Launch](https://www.contentstack.com/d
 
 ---
 
-## ⚡ Quick Start (Recommended)
+## 📋 Table of Contents
 
-Bootstrap your edge environment in seconds using our automated initializer. Run this command from your **project root**:
+- [Quick Start](#-quick-start)
+- [Usage Flow](#-usage-flow)
+- [Complete API Reference](#-complete-api-reference)
+- [Real-World Examples](#-real-world-examples)
+- [CLI Commands](#-cli-commands)
+- [Platform Support](#-platform-support)
+
+---
+
+## ⚡ Quick Start
+
+### Step 1: Install the Package
 
 ```bash
-# Install the package
 npm install @aryanbansal-launch/edge-utils
+```
 
-# Initialize Edge Functions
+### Step 2: Initialize Edge Functions
+
+Run this command from your **project root** (where `package.json` is located):
+
+```bash
 npx create-launch-edge
 ```
 
-This command will automatically create the `functions/` directory and a production-ready `[proxy].edge.js` boilerplate handler.
+This automatically creates:
+- `functions/` directory
+- `functions/[proxy].edge.js` with production-ready boilerplate
+
+### Step 3: Customize & Deploy
+
+1. Open `functions/[proxy].edge.js`
+2. Customize the utilities based on your needs
+3. Deploy to Contentstack Launch
+
+**Need help?** Run:
+```bash
+npx launch-help
+```
 
 ---
 
-## ✨ Features & Deep Dive
+## 🔄 Usage Flow
 
-### 🛡️ Security & Access Control
-- **[Block AI Crawlers](https://www.contentstack.com/docs/developers/launch/blocking-ai-crawlers)**: Automatically detects and rejects requests from known scrapers (GPTBot, ClaudeBot, etc.) to protect your content and server resources.
-- **[Restricted Default Domains](https://www.contentstack.com/docs/developers/launch/blocking-default-launch-domains-from-google-search)**: By default, Launch provides a `*.contentstackapps.com` domain. This utility forces visitors to your custom domain, which is essential for SEO (preventing duplicate content) and professional branding.
-- **[IP Access Control](https://www.contentstack.com/docs/developers/launch/ip-based-access-control-using-edge-functions)**: Create a lightweight firewall at the edge to whitelist internal teams or block malicious IPs before they hit your application logic.
+### Understanding Edge Functions
 
-### ⚛️ Next.js Optimization
-- **[RSC Header Fix](https://www.contentstack.com/docs/developers/launch/handling-nextjs-rsc-issues-on-launch)**: Next.js React Server Components (RSC) use a special `rsc` header. Sometimes, proxies or caches can incorrectly serve RSC data when a full page load is expected. This utility detects these edge cases and strips the header to ensure the correct response type is served.
+Edge Functions in Contentstack Launch act as **middleware** that runs before requests reach your origin server. Think of them as a chain of checks and transformations:
 
-### 📍 Performance & Geo-Awareness
-- **[Geo-Location Access](https://www.contentstack.com/docs/developers/launch/geolocation-headers-in-launch)**: Contentstack Launch injects geography data into request headers. This utility parses those headers into a clean object (`country`, `city`, `region`, etc.), enabling you to personalize content or restrict features based on user location.
-- **[Cache Priming](https://www.contentstack.com/docs/developers/launch/cache-priming)**: Use the `launch-config` CLI to pre-load critical URLs into the edge cache, eliminating "cold start" latency for your first visitors after a deployment.
+```
+User Request → Edge Function → Your Application
+```
 
-### 🔀 Smart Routing
-- **Declarative Redirects**: Handle complex, logic-based redirects at runtime.
-- **Runtime vs Config**: 
-    - Use **`launch.json`** ([Static Redirects](https://www.contentstack.com/docs/developers/launch/edge-url-redirects)) for high-performance, simple path-to-path mapping.
-    - Use **`redirectIfMatch`** (this library) for dynamic redirects that require logic, such as checking cookies, headers, or geo-location before redirecting.
+### Basic Pattern
 
----
+Every utility follows this pattern:
 
-## 🛠️ Detailed Usage Example
+```javascript
+const result = utilityFunction(request, options);
+if (result) return result;  // Early return if condition met
+// Continue to next check...
+```
+
+### Complete Handler Example
 
-Your `functions/[proxy].edge.js` acts as a **middleware chain**. You can layer these utilities to create complex edge logic:
+Here's how utilities work together in `functions/[proxy].edge.js`:
 
 ```javascript
 import {
@@ -55,74 +81,828 @@ import {
   handleNextJS_RSC,
   blockAICrawlers,
   ipAccessControl,
+  protectWithBasicAuth,
   redirectIfMatch,
   getGeoHeaders,
+  jsonResponse,
   passThrough
 } from "@aryanbansal-launch/edge-utils";
 
 export default async function handler(request, context) {
-  // 1. 🛡️ Force Custom Domain (SEO Best Practice)
-  // Blocks access via *.contentstackapps.com
+  // 1️⃣ SECURITY LAYER
+  // Block default domains (SEO best practice)
   const domainCheck = blockDefaultDomains(request);
   if (domainCheck) return domainCheck;
 
-  // 2. ⚛️ Fix Next.js RSC Header issues 
-  // Prevents "JSON-only" responses on page refreshes
+  // Block AI bots and crawlers
+  const botCheck = blockAICrawlers(request);
+  if (botCheck) return botCheck;
+
+  // IP-based access control
+  const ipCheck = ipAccessControl(request, {
+    allow: ["203.0.113.10", "198.51.100.5"]
+  });
+  if (ipCheck) return ipCheck;
+
+  // 2️⃣ AUTHENTICATION LAYER
+  // Protect staging environments
+  const auth = await protectWithBasicAuth(request, {
+    hostnameIncludes: "staging.myapp.com",
+    username: "admin",
+    password: "securepass123"
+  });
+  if (auth && auth.status === 401) return auth;
+
+  // 3️⃣ FRAMEWORK FIXES
+  // Fix Next.js RSC header issues
   const rscCheck = await handleNextJS_RSC(request, {
-    affectedPaths: ["/shop", "/about"]
+    affectedPaths: ["/shop", "/products", "/about"]
   });
   if (rscCheck) return rscCheck;
 
-  // 3. 🤖 Block Aggressive Bots
+  // 4️⃣ ROUTING LAYER
+  // Handle redirects
+  const redirect = redirectIfMatch(request, {
+    path: "/old-page",
+    to: "/new-page",
+    status: 301
+  });
+  if (redirect) return redirect;
+
+  // 5️⃣ PERSONALIZATION
+  // Get user's location
+  const geo = getGeoHeaders(request);
+  if (geo.country === "US") {
+    console.log(`US visitor from ${geo.city}, ${geo.region}`);
+  }
+
+  // 6️⃣ CUSTOM API ENDPOINTS
+  const url = new URL(request.url);
+  if (url.pathname === "/api/health") {
+    return jsonResponse({
+      status: "healthy",
+      region: geo.region,
+      timestamp: Date.now()
+    });
+  }
+
+  // 7️⃣ DEFAULT: Pass to origin
+  return passThrough(request);
+}
+```
+
+---
+
+## 📚 Complete API Reference
+
+### 🛡️ Security & Access Control
+
+#### `blockAICrawlers(request, bots?)`
+
+Block AI crawlers and bots from accessing your site.
+
+**Parameters:**
+- `request` (Request) - The incoming request object
+- `bots` (string[], optional) - Custom list of bot user-agents to block
+
+**Returns:** `Response | null`
+- Returns `403 Forbidden` if bot detected
+- Returns `null` if no bot detected (continue processing)
+
+**Default Blocked Bots:**
+The following bots are blocked by default (case-insensitive):
+- `claudebot` - Anthropic's Claude AI crawler
+- `gptbot` - OpenAI's GPT crawler
+- `googlebot` - Google's web crawler
+- `bingbot` - Microsoft Bing's crawler
+- `ahrefsbot` - Ahrefs SEO crawler
+- `yandexbot` - Yandex search engine crawler
+- `semrushbot` - SEMrush SEO tool crawler
+- `mj12bot` - Majestic SEO crawler
+- `facebookexternalhit` - Facebook's link preview crawler
+- `twitterbot` - Twitter's link preview crawler
+
+**Example:**
+```javascript
+// Use default bot list
+const response = blockAICrawlers(request);
+if (response) return response;
+
+// Custom bot list
+const response = blockAICrawlers(request, [
+  "gptbot",
+  "claudebot",
+  "my-custom-bot"
+]);
+if (response) return response;
+```
+
+**Use Cases:**
+- Protect content from AI scraping
+- Reduce server load from aggressive crawlers
+- Comply with content usage policies
+
+---
+
+#### `blockDefaultDomains(request, options?)`
+
+Block access via default Launch domains (`*.contentstackapps.com`).
+
+**Parameters:**
+- `request` (Request) - The incoming request object
+- `options` (object, optional)
+  - `domainToBlock` (string) - Custom domain to block (default: "contentstackapps.com")
+
+**Returns:** `Response | null`
+- Returns `403 Forbidden` if default domain detected
+- Returns `null` if custom domain used
+
+**Example:**
+```javascript
+// Block default Launch domain
+const response = blockDefaultDomains(request);
+if (response) return response;
+
+// Block custom domain
+const response = blockDefaultDomains(request, {
+  domainToBlock: "myolddomain.com"
+});
+if (response) return response;
+```
+
+**Use Cases:**
+- Force users to custom domain for SEO
+- Prevent duplicate content indexing
+- Professional branding
+
+**Learn More:** [Blocking Default Launch Domains](https://www.contentstack.com/docs/developers/launch/blocking-default-launch-domains-from-google-search)
+
+---
+
+#### `ipAccessControl(request, options)`
+
+Whitelist or blacklist IPs at the edge.
+
+**Parameters:**
+- `request` (Request) - The incoming request object
+- `options` (object)
+  - `allow` (string[], optional) - Whitelist of allowed IPs
+  - `deny` (string[], optional) - Blacklist of denied IPs
+
+**Returns:** `Response | null`
+- Returns `403 Forbidden` if IP blocked
+- Returns `null` if IP allowed
+
+**Example:**
+```javascript
+// Whitelist specific IPs (only these can access)
+const response = ipAccessControl(request, {
+  allow: ["203.0.113.10", "198.51.100.5"]
+});
+if (response) return response;
+
+// Blacklist specific IPs
+const response = ipAccessControl(request, {
+  deny: ["192.0.2.100", "192.0.2.101"]
+});
+if (response) return response;
+
+// Combine both (deny takes precedence)
+const response = ipAccessControl(request, {
+  allow: ["203.0.113.0/24"],  // Allow subnet
+  deny: ["203.0.113.50"]       // Except this one
+});
+if (response) return response;
+```
+
+**Use Cases:**
+- Restrict admin panels to office IPs
+- Block malicious IPs
+- Create staging environment access control
+
+**Learn More:** [IP-Based Access Control](https://www.contentstack.com/docs/developers/launch/ip-based-access-control-using-edge-functions)
+
+---
+
+#### `protectWithBasicAuth(request, options)`
+
+Add Basic Authentication to protect environments.
+
+**Parameters:**
+- `request` (Request) - The incoming request object
+- `options` (object)
+  - `hostnameIncludes` (string) - Protect URLs containing this hostname
+  - `username` (string) - Username for authentication
+  - `password` (string) - Password for authentication
+  - `realm` (string, optional) - Auth realm name (default: "Protected Area")
+
+**Returns:** `Promise<Response> | null`
+- Returns `401 Unauthorized` if auth fails
+- Returns authenticated response if credentials valid
+- Returns `null` if hostname doesn't match
+
+**Example:**
+```javascript
+// Protect staging environment
+const auth = await protectWithBasicAuth(request, {
+  hostnameIncludes: "staging.myapp.com",
+  username: "admin",
+  password: "securepass123",
+  realm: "Staging Environment"
+});
+if (auth && auth.status === 401) return auth;
+
+// Protect specific path pattern
+const url = new URL(request.url);
+if (url.pathname.startsWith("/admin")) {
+  const auth = await protectWithBasicAuth(request, {
+    hostnameIncludes: url.hostname,
+    username: "admin",
+    password: "adminpass"
+  });
+  if (auth && auth.status === 401) return auth;
+}
+```
+
+**Use Cases:**
+- Protect staging/dev environments
+- Quick password protection for demos
+- Restrict access to admin areas
+
+**Security Note:** For production, use proper authentication systems. Basic Auth credentials are base64-encoded, not encrypted.
+
+**Learn More:** [Password Protection for Environments](https://www.contentstack.com/docs/developers/launch/password-protection-for-environments)
+
+---
+
+### 🔀 Routing & Redirects
+
+#### `redirectIfMatch(request, options)`
+
+Conditional redirects based on path and method.
+
+**Parameters:**
+- `request` (Request) - The incoming request object
+- `options` (object)
+  - `path` (string) - Path to match
+  - `to` (string) - Destination path
+  - `method` (string, optional) - HTTP method to match (e.g., "GET", "POST")
+  - `status` (number, optional) - HTTP status code (default: 301)
+
+**Returns:** `Response | null`
+- Returns redirect response if path matches
+- Returns `null` if no match
+
+**Example:**
+```javascript
+// Simple redirect
+const redirect = redirectIfMatch(request, {
+  path: "/old-page",
+  to: "/new-page",
+  status: 301  // Permanent redirect
+});
+if (redirect) return redirect;
+
+// Temporary redirect
+const redirect = redirectIfMatch(request, {
+  path: "/maintenance",
+  to: "/coming-soon",
+  status: 302  // Temporary redirect
+});
+if (redirect) return redirect;
+
+// Method-specific redirect
+const redirect = redirectIfMatch(request, {
+  path: "/api/old-endpoint",
+  method: "POST",
+  to: "/api/v2/endpoint",
+  status: 308  // Permanent redirect (preserves method)
+});
+if (redirect) return redirect;
+```
+
+**Use Cases:**
+- SEO-friendly URL changes
+- Migrate old URLs to new structure
+- A/B testing redirects
+- Maintenance mode redirects
+
+**When to Use:**
+- **Edge Functions (this utility)**: Dynamic redirects requiring logic (cookies, headers, geo)
+- **launch.json**: Static path-to-path redirects (better performance)
+
+**Learn More:** [Edge URL Redirects](https://www.contentstack.com/docs/developers/launch/edge-url-redirects)
+
+---
+
+### ⚛️ Next.js Optimization
+
+#### `handleNextJS_RSC(request, options)`
+
+Fix Next.js React Server Components header issues.
+
+**Parameters:**
+- `request` (Request) - The incoming request object
+- `options` (object)
+  - `affectedPaths` (string[]) - Array of paths with RSC issues
+
+**Returns:** `Promise<Response> | null`
+- Returns modified response if RSC issue detected
+- Returns `null` if no issue
+
+**Example:**
+```javascript
+// Fix specific pages
+const rsc = await handleNextJS_RSC(request, {
+  affectedPaths: ["/shop", "/products", "/about"]
+});
+if (rsc) return rsc;
+
+// Fix all dynamic routes
+const rsc = await handleNextJS_RSC(request, {
+  affectedPaths: ["/blog", "/products", "/categories"]
+});
+if (rsc) return rsc;
+```
+
+**What It Does:**
+Next.js RSC uses a special `rsc: 1` header. Sometimes, caches incorrectly serve RSC data (JSON) when a full page load is expected. This utility detects these cases and strips the header to ensure correct response type.
+
+**Use Cases:**
+- Fix "JSON showing instead of page" issues
+- Resolve RSC caching problems
+- Ensure proper page hydration
+
+**Learn More:** [Handling Next.js RSC Issues](https://www.contentstack.com/docs/developers/launch/handling-nextjs-rsc-issues-on-launch)
+
+---
+
+### 📍 Geo-Location
+
+#### `getGeoHeaders(request)`
+
+Extract geo-location data from Launch headers.
+
+**Parameters:**
+- `request` (Request) - The incoming request object
+
+**Returns:** Object with geo data
+```typescript
+{
+  country: string | null,    // ISO country code (e.g., "US")
+  region: string | null,     // Region/state code (e.g., "CA")
+  city: string | null,       // City name (e.g., "San Francisco")
+  latitude: string | null,   // Latitude coordinate
+  longitude: string | null   // Longitude coordinate
+}
+```
+
+**Example:**
+```javascript
+// Get user location
+const geo = getGeoHeaders(request);
+
+// Country-based logic
+if (geo.country === "US") {
+  console.log(`US visitor from ${geo.city}, ${geo.region}`);
+}
+
+// Region-specific content
+if (geo.country === "US" && geo.region === "CA") {
+  // Show California-specific content
+}
+
+// Distance-based logic
+if (geo.latitude && geo.longitude) {
+  const userLat = parseFloat(geo.latitude);
+  const userLon = parseFloat(geo.longitude);
+  // Calculate distance to store, etc.
+}
+
+// Redirect based on location
+const geo = getGeoHeaders(request);
+if (geo.country === "FR") {
+  return Response.redirect("https://fr.mysite.com", 302);
+}
+```
+
+**Use Cases:**
+- Personalize content by location
+- Show region-specific pricing
+- Redirect to country-specific sites
+- Display nearest store locations
+- Comply with regional regulations
+
+**Learn More:** [Geolocation Headers in Launch](https://www.contentstack.com/docs/developers/launch/geolocation-headers-in-launch)
+
+---
+
+### 📤 Response Utilities
+
+#### `jsonResponse(body, init?)`
+
+Create JSON responses easily.
+
+**Parameters:**
+- `body` (object) - JSON-serializable object
+- `init` (ResponseInit, optional) - Additional response options (status, headers, etc.)
+
+**Returns:** `Response` with `Content-Type: application/json`
+
+**Example:**
+```javascript
+// Simple JSON response
+return jsonResponse({ status: "ok", message: "Success" });
+
+// With custom status
+return jsonResponse(
+  { error: "Not found" },
+  { status: 404 }
+);
+
+// With custom headers
+return jsonResponse(
+  { data: [...] },
+  {
+    status: 200,
+    headers: {
+      "Cache-Control": "max-age=3600",
+      "X-Custom-Header": "value"
+    }
+  }
+);
+
+// API endpoint example
+const url = new URL(request.url);
+if (url.pathname === "/api/user") {
+  const geo = getGeoHeaders(request);
+  return jsonResponse({
+    user: "john_doe",
+    location: {
+      country: geo.country,
+      city: geo.city
+    },
+    timestamp: Date.now()
+  });
+}
+```
+
+**Use Cases:**
+- Create API endpoints at the edge
+- Return structured error messages
+- Build serverless functions
+
+---
+
+#### `passThrough(request)`
+
+Forward request to origin server.
+
+**Parameters:**
+- `request` (Request) - The incoming request object
+
+**Returns:** `Promise<Response>` from origin
+
+**Example:**
+```javascript
+// Default: pass everything through
+return passThrough(request);
+
+// After all checks
+export default async function handler(request, context) {
+  // ... all your checks ...
+  
+  // If nothing matched, pass to origin
+  return passThrough(request);
+}
+```
+
+**Use Cases:**
+- Default fallback after edge logic
+- Forward requests that don't need edge processing
+
+---
+
+### ⚙️ Configuration
+
+#### `generateLaunchConfig(options)`
+
+Generate `launch.json` configuration programmatically.
+
+**Parameters:**
+- `options` (object)
+  - `redirects` (LaunchRedirect[], optional)
+  - `rewrites` (LaunchRewrite[], optional)
+  - `cache` (object, optional)
+    - `cachePriming` (object)
+      - `urls` (string[])
+
+**Returns:** `LaunchConfig` object
+
+**Types:**
+```typescript
+interface LaunchRedirect {
+  source: string;
+  destination: string;
+  statusCode?: number;
+  response?: {
+    headers?: Record<string, string>;
+  };
+}
+
+interface LaunchRewrite {
+  source: string;
+  destination: string;
+}
+```
+
+**Example:**
+```javascript
+import { generateLaunchConfig } from "@aryanbansal-launch/edge-utils";
+import fs from "fs";
+
+const config = generateLaunchConfig({
+  redirects: [
+    {
+      source: "/old-blog/:slug",
+      destination: "/blog/:slug",
+      statusCode: 301
+    },
+    {
+      source: "/products",
+      destination: "/shop",
+      statusCode: 308
+    }
+  ],
+  rewrites: [
+    {
+      source: "/api/:path*",
+      destination: "https://api.mybackend.com/:path*"
+    }
+  ],
+  cache: {
+    cachePriming: {
+      urls: ["/", "/about", "/products", "/contact"]
+    }
+  }
+});
+
+// Write to launch.json
+fs.writeFileSync("launch.json", JSON.stringify(config, null, 2));
+```
+
+**Use Cases:**
+- Generate config from CMS data
+- Automate bulk redirects
+- Dynamic configuration management
+
+---
+
+## 🎯 Real-World Examples
+
+### Example 1: E-Commerce Site
+
+```javascript
+export default async function handler(request, context) {
+  const url = new URL(request.url);
+  const geo = getGeoHeaders(request);
+
+  // 1. Block bots to reduce costs
   const botCheck = blockAICrawlers(request);
   if (botCheck) return botCheck;
 
-  // 4. 🧱 Firewall
-  const ipCheck = ipAccessControl(request, { allow: ["203.0.113.10"] });
-  if (ipCheck) return ipCheck;
+  // 2. Geo-based redirects
+  if (geo.country === "UK" && !url.hostname.includes("uk.")) {
+    return Response.redirect(`https://uk.myshop.com${url.pathname}`, 302);
+  }
 
-  // 5. 🔀 Logic-Based Redirects
+  // 3. Maintenance mode for specific regions
+  if (geo.country === "US" && url.pathname.startsWith("/checkout")) {
+    return jsonResponse(
+      { error: "Checkout temporarily unavailable in your region" },
+      { status: 503 }
+    );
+  }
+
+  // 4. Product redirects
   const redirect = redirectIfMatch(request, {
-    path: "/legacy-page",
-    to: "/new-page",
+    path: "/products/old-sku-123",
+    to: "/products/new-sku-456",
     status: 301
   });
   if (redirect) return redirect;
 
-  // 6. 📍 Personalization
+  return passThrough(request);
+}
+```
+
+### Example 2: Multi-Environment Setup
+
+```javascript
+export default async function handler(request, context) {
+  const url = new URL(request.url);
+
+  // 1. Protect staging with Basic Auth
+  if (url.hostname.includes("staging")) {
+    const auth = await protectWithBasicAuth(request, {
+      hostnameIncludes: "staging",
+      username: "team",
+      password: process.env.STAGING_PASSWORD || "defaultpass"
+    });
+    if (auth && auth.status === 401) return auth;
+  }
+
+  // 2. Restrict dev environment to office IPs
+  if (url.hostname.includes("dev")) {
+    const ipCheck = ipAccessControl(request, {
+      allow: ["203.0.113.0/24"]  // Office IP range
+    });
+    if (ipCheck) return ipCheck;
+  }
+
+  // 3. Block default domain on production
+  if (url.hostname.includes("myapp.com")) {
+    const domainCheck = blockDefaultDomains(request);
+    if (domainCheck) return domainCheck;
+  }
+
+  return passThrough(request);
+}
+```
+
+### Example 3: Next.js App with API Routes
+
+```javascript
+export default async function handler(request, context) {
+  const url = new URL(request.url);
   const geo = getGeoHeaders(request);
-  if (geo.country === "UK") {
-    // Custom logic for UK visitors...
+
+  // 1. Fix RSC issues on dynamic pages
+  const rscCheck = await handleNextJS_RSC(request, {
+    affectedPaths: ["/blog", "/products", "/categories"]
+  });
+  if (rscCheck) return rscCheck;
+
+  // 2. Edge API endpoints
+  if (url.pathname === "/api/geo") {
+    return jsonResponse({
+      country: geo.country,
+      region: geo.region,
+      city: geo.city
+    });
+  }
+
+  if (url.pathname === "/api/health") {
+    return jsonResponse({
+      status: "healthy",
+      timestamp: Date.now(),
+      region: geo.region
+    });
+  }
+
+  // 3. Block bots from expensive pages
+  if (url.pathname.startsWith("/search")) {
+    const botCheck = blockAICrawlers(request);
+    if (botCheck) return botCheck;
   }
 
-  // 7. 🚀 Pass through to Origin
   return passThrough(request);
 }
 ```
 
 ---
 
-## ⚙️ Configuration CLI
+## 🛠️ CLI Commands
 
-Manage your `launch.json` file interactively to handle bulk settings:
+### `npx create-launch-edge`
 
+Initialize edge functions with production-ready boilerplate.
+
+**What it does:**
+1. Checks you're in project root (where `package.json` exists)
+2. Creates `functions/` directory if needed
+3. Generates `functions/[proxy].edge.js` with example code
+
+**Usage:**
+```bash
+cd /path/to/your/project
+npx create-launch-edge
+```
+
+**Output:**
+```
+🚀 create-launch-edge: Contentstack Launch Initializer
+
+✨ New: Created /functions directory
+✨ New: Created /functions/[proxy].edge.js
+
+🎉 Setup Complete!
+
+Next Steps:
+1. Open functions/[proxy].edge.js
+2. Customize your redirects, auth, and RSC paths
+3. Deploy your project to Contentstack Launch
+```
+
+---
+
+### `npx launch-config`
+
+Interactive CLI to manage `launch.json` configuration.
+
+**What it does:**
+- Add/manage redirects
+- Configure rewrites
+- Set up cache priming URLs
+- Preserves existing configuration
+
+**Usage:**
 ```bash
 npx launch-config
 ```
 
-### Supported Settings:
-- **Bulk Redirects**: Add multiple sources and destinations easily.
-- **Rewrites**: Map internal paths to external APIs or micro-services.
-- **Cache Priming**: Add a comma-separated list of URLs to warm up the CDN.
+**Interactive Prompts:**
+```
+🚀 Launch Configuration Generator
+
+Do you want to add a Redirect? (y/n): y
+   Source path (e.g., /source): /old-page
+   Destination path (e.g., /destination): /new-page
+   Status code (default 308): 301
+   ✔ Redirect added.
+
+Do you want to add a Redirect? another? (y/n): n
+
+Do you want to add a Rewrite? (y/n): y
+   Source path (e.g., /api/*): /api/*
+   Destination URL: https://backend.myapp.com/api/*
+   ✔ Rewrite added.
+
+Do you want to add Cache Priming URLs? (y/n): y
+Note: Only relative paths are supported. No Regex/Wildcards.
+Enter URLs separated by commas (e.g., /home,/about,/shop): /,/about,/products
+
+✅ Successfully updated launch.json!
+```
+
+**Learn More:**
+- [Static Redirects](https://www.contentstack.com/docs/developers/launch/edge-url-redirects)
+- [Cache Priming](https://www.contentstack.com/docs/developers/launch/cache-priming)
+
+---
+
+### `npx launch-help`
+
+Display complete reference guide with all methods and examples.
+
+**Usage:**
+```bash
+npx launch-help
+```
+
+**Shows:**
+- All available methods with parameters
+- Return types and examples
+- CLI commands
+- Quick links to documentation
 
 ---
 
 ## 🌐 Platform Support
 
-This library is exclusively optimized for **[Contentstack Launch](https://www.contentstack.com/docs/developers/launch)**. It assumes an environment where `Request`, `Response`, and standard Edge Global APIs are available.
+This library is exclusively optimized for **[Contentstack Launch](https://www.contentstack.com/docs/developers/launch)**. It assumes an environment where:
+- Standard Web APIs (`Request`, `Response`, `fetch`) are available
+- Edge runtime environment
+- Contentstack Launch geo-location headers
+
+**Not compatible with:**
+- Node.js servers
+- Traditional hosting platforms
+- Other edge platforms (Cloudflare Workers, Vercel Edge, etc.)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+**Repository:** https://github.com/AryanBansal-launch/launch-edge-utils
 
 ---
 
 ## 📄 License
 
 Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+## 🔗 Useful Links
+
+- **[Contentstack Launch Documentation](https://www.contentstack.com/docs/developers/launch)**
+- **[Edge Functions Guide](https://www.contentstack.com/docs/developers/launch/edge-functions)**
+- **[NPM Package](https://www.npmjs.com/package/@aryanbansal-launch/edge-utils)**
+- **[GitHub Repository](https://github.com/AryanBansal-launch/launch-edge-utils)**
+
+---
+
+**Made with ❤️ for the Contentstack Launch community**