@aryanbansal-launch/edge-utils 0.1.0 → 0.1.2

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./auth/basic-auth.js";
 export * from "./security/ip-access.js";
 export * from "./security/block-bots.js";
 export * from "./geo/geo-headers.js";
+export * from "./nextjs/rsc.js";

package/dist/nextjs/rsc.js

@@ -0,0 +1,16 @@
+export function handleNextJS_RSC(request, options) {
+    const RSC_HEADER = 'rsc';
+    const RSC_HEADER_VALUE = '1';
+    const RSC_QUERY_PARAM = '_rsc';
+    const parsedUrl = new URL(request.url);
+    const route = parsedUrl.pathname;
+    const rscQueryParamExists = !!parsedUrl.searchParams.get(RSC_QUERY_PARAM);
+    const rscHeaderExists = request.headers.get(RSC_HEADER) === RSC_HEADER_VALUE;
+    const isAffectedPath = options.affectedPaths.includes(route);
+    if (isAffectedPath && !rscQueryParamExists && rscHeaderExists) {
+        const modifiedRequest = new Request(request);
+        modifiedRequest.headers.delete(RSC_HEADER);
+        return fetch(modifiedRequest);
+    }
+    return null;
+}

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@aryanbansal-launch/edge-utils",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc"
   }

package/readme.md

@@ -1,29 +1,35 @@
-# Edge Utils
+# 🚀 Edge Utils
 
-A collection of high-performance utilities designed for Edge Computing environments (like Cloudflare Workers, Vercel Edge Functions, or Contentstack Launch). These utilities help you handle common tasks like authentication, security, redirection, and geo-location directly at the edge.
+[![npm version](https://img.shields.io/npm/v/@launch/edge-utils.svg)](https://www.npmjs.com/package/@launch/edge-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Platform Support](https://img.shields.io/badge/Platform-Edge-blueviolet.svg)](#platform-support)
 
-## Table of Contents
+A lightweight, developer-friendly toolkit for **Edge Computing**. Speed up your development on platforms like Cloudflare Workers, Vercel Edge, and Contentstack Launch with production-ready utilities for security, authentication, and routing.
 
-- [Installation](#installation)
-- [Usage Example](#usage-example)
-- [API Reference](#api-reference)
-  - [Security](#security)
-  - [Authentication](#authentication)
-  - [Redirection](#redirection)
-  - [Geo Location](#geo-location)
-  - [Responses](#responses)
+---
 
-## Installation
+## ✨ Features
 
-Install the package via npm:
+- 🛡️ **Security First**: Block AI crawlers and manage IP access with ease.
+- 🔐 **Edge Auth**: Implement Basic Auth directly at the edge for specific hostnames.
+- 📍 **Geo-Aware**: Easily extract location data from request headers.
+- ⚛️ **Next.js Ready**: Built-in fixes for RSC header issues on edge proxies.
+- 🔀 **Smart Routing**: Declarative redirects based on path and method.
+- ⚡ **Zero Dependencies**: Lightweight and optimized for edge runtime limits.
+
+---
+
+## 📦 Installation
 
 ```bash
 npm install @launch/edge-utils
 ```
 
-## Usage Example
+---
+
+## 🛠️ Usage Example
 
-Here is a comprehensive example of how to use multiple utilities in a single edge handler:
+Transform your edge handler into a powerful middleware chain:
 
 ```typescript
 import {
@@ -33,77 +39,134 @@ import {
   protectWithBasicAuth,
   ipAccessControl,
   blockAICrawlers,
-  getGeoHeaders
+  getGeoHeaders,
+  handleNextJS_RSC
 } from "@launch/edge-utils";
 
 export default async function handler(request: Request) {
-  // 1. Block known AI crawlers and bots
+  // 1. ⚛️ Fix Next.js RSC issues for specific paths
+  const rscResponse = await handleNextJS_RSC(request, {
+    affectedPaths: ["/my-rsc-page", "/another-page"]
+  });
+  if (rscResponse) return rscResponse;
+
+  // 2. 🛡️ Block AI bots immediately
   const botResponse = blockAICrawlers(request);
   if (botResponse) return botResponse;
 
-  // 2. IP-based access control
+  // 2. 🧱 IP Whitelisting
   const ipResponse = ipAccessControl(request, { allow: ["203.0.113.10"] });
   if (ipResponse) return ipResponse;
 
-  // 3. Basic Authentication for specific hostnames
+  // 3. 🔐 Domain-specific Basic Auth
   const authResponse = await protectWithBasicAuth(request, {
-    hostnameIncludes: "test-protected-domain.dev",
+    hostnameIncludes: "staging.myapp.com",
     username: "admin",
-    password: "securepassword"
+    password: "securepassword123"
   });
   if (authResponse && authResponse.status === 401) return authResponse;
 
-  // 4. Conditional Redirection
+  // 4. 🔀 SEO-friendly Redirects
   const redirectResponse = redirectIfMatch(request, {
-    path: "/old-page",
-    method: "GET",
-    to: "/new-page"
+    path: "/legacy-url",
+    to: "/modern-url",
+    status: 301
   });
   if (redirectResponse) return redirectResponse;
 
-  // 5. Handle specific routes
-  if (new URL(request.url).pathname === "/api/status") {
-    return jsonResponse({ status: "ok", timestamp: new Date() });
+  // 5. 📍 Geo-Location Access
+  const geo = getGeoHeaders(request);
+  if (geo.country === "US") {
+    console.log(`User from ${geo.city}, ${geo.region}`);
   }
 
-  // 6. Access Geo-location headers
-  const geo = getGeoHeaders(request);
-  console.log("Request from country:", geo.country);
+  // 6. 📤 Custom JSON Responses
+  if (new URL(request.url).pathname === "/api/health") {
+    return jsonResponse({ status: "healthy", region: geo.region });
+  }
 
-  // 7. Pass through the request if no utility intercepted it
+  // 7. 🚀 Pass through to origin
   return passThrough(request);
 }
 ```
 
-## API Reference
+---
+
+## 📖 API Reference
+
+### 🛡️ Security
+
+#### `blockAICrawlers`
+Blocks common AI crawlers (GPTBot, ClaudeBot, etc.) to protect your content from scraping.
+- **Parameters**: `request: Request`, `bots?: string[]` (optional list to override defaults)
+- **Returns**: `Response` (403) or `null`.
+
+#### `ipAccessControl`
+Simple firewall for your edge function.
+- **Options**:
+  - `allow`: Array of IPs allowed to access.
+  - `deny`: Array of IPs to block.
+- **Returns**: `Response` (403) or `null`.
+
+### 🔐 Authentication
+
+#### `protectWithBasicAuth`
+Prompt for credentials based on the hostname.
+- **Options**:
+  - `hostnameIncludes`: Match substring in hostname (e.g., ".dev").
+  - `username`: Required username.
+  - `password`: Required password.
+  - `realm`: Optional realm name for the auth prompt.
+- **Returns**: `Promise<Response>` or `null`.
+
+### 🔀 Redirection
+
+#### `redirectIfMatch`
+Perform redirects directly at the edge to reduce latency.
+- **Options**:
+  - `path`: The path to match.
+  - `method`: HTTP method to match (optional, defaults to any).
+  - `to`: Target path or URL.
+  - `status`: HTTP status code (default: 301).
+- **Returns**: `Response` (Redirect) or `null`.
+
+### 📍 Geo Location
+
+#### `getGeoHeaders`
+Extracts geo-information provided by edge platform headers.
+- **Returns**: Object with `country`, `region`, `city`, `latitude`, `longitude`.
 
-### Security
+### ⚛️ Next.js
 
-#### `blockAICrawlers(request: Request, bots?: string[]): Response | null`
-Blocks common AI crawlers (like GPTBot, ClaudeBot) based on the `User-Agent` header. Returns a `403 Forbidden` response if a bot is detected, otherwise returns `null`.
+#### `handleNextJS_RSC`
+Handles Next.js React Server Component (RSC) header issues on Contentstack Launch. It detects requests to "affected paths" that have the `rsc` header but lack the `_rsc` query parameter, and strips the header to prevent proxy/caching issues.
+- **Options**:
+  - `affectedPaths`: Array of pathnames (e.g., `['/shop', '/about']`) where this fix should apply.
+- **Returns**: `Promise<Response>` (the re-fetched request without RSC header) or `null`.
 
-#### `ipAccessControl(request: Request, options: { allow?: string[], deny?: string[] }): Response | null`
-Restricts access based on the client's IP address. You can provide an `allow` list or a `deny` list.
+---
 
-### Authentication
+## 🌐 Platform Support
 
-#### `protectWithBasicAuth(request: Request, options: AuthOptions): Promise<Response> | null`
-Implements HTTP Basic Authentication. If the hostname matches `hostnameIncludes` and credentials are missing or invalid, it returns a `401 Unauthorized` response with the appropriate headers.
+Optimized for:
+- [Contentstack Launch](https://www.contentstack.com/docs/developers/launch)
+- [Vercel Edge Functions](https://vercel.com/docs/concepts/functions/edge-functions)
+- [Cloudflare Workers](https://workers.cloudflare.com/)
 
-### Redirection
+---
 
-#### `redirectIfMatch(request: Request, options: RedirectOptions): Response | null`
-Redirects the request if the URL path and HTTP method match the provided options.
+## 🤝 Contributing
 
-### Geo Location
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-#### `getGeoHeaders(request: Request): Record<string, string | null>`
-Extracts geo-location information (country, city, region, etc.) from the request headers typically provided by edge platforms.
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
 
-### Responses
+---
 
-#### `jsonResponse(data: any, init?: ResponseInit): Response`
-A helper to return a JSON response with the correct `Content-Type` header.
+## 📄 License
 
-#### `passThrough(request: Request): Response`
-Continues the request processing by calling `fetch(request)`. Useful at the end of an edge function.
+Distributed under the MIT License. See `LICENSE` for more information.