rkk-next 1.1.2 → 2.0.0

package/README.md

@@ -380,11 +380,20 @@ See [Backend Utilities Documentation](docs/BACKEND.md) for complete API referenc
 
 **System Requirements:**
 
-- Next.js `>= 12.0.0`
+- Next.js `>= 14.0.0 < 16.0.0`
 - React `>= 17.0.0`
 - Node.js `>= 16.0.0`
 - TypeScript `>= 4.5.0` (optional but recommended)
 
+### Analytics Endpoint (Optional)
+
+To send web vitals to your backend, set either environment variable:
+
+- `NEXT_PUBLIC_RKK_ANALYTICS_ENDPOINT`
+- `RKK_ANALYTICS_ENDPOINT`
+
+If neither is set, metrics are not sent over the network by default.
+
 ---
 
 ## 🎓 Learn More
@@ -480,38 +489,3 @@ Full-Stack Developer | Next.js & Web3 Specialist
 [Get Started](./docs/QUICKSTART.md) · [Documentation](./docs/DOCS.md) · [Examples](./examples/) · [Changelog](./CHANGELOG.md)
 
 </div>
-MIT License © 2025 [Rohit Kumar Kundu](https://github.com/ROHIT8759)
-
-Free to use, modify, and distribute. See [LICENSE](./LICENSE) for details.
-
-## ⭐ Support the Project
-
-If you find rkk-next helpful:
-
-- ⭐ **Star the repo** on GitHub
-- 🐛 **Report issues** to help improve the SDK
-- 🤝 **Contribute** with PRs and feature ideas
-- 📢 **Share** with other Next.js developers
-- 💬 **Join discussions** and share your use cases
-
----
-
-**Made with ❤️ for the Next.js community**
-
-[Get Started](./docs/QUICKSTART.md) | [Documentation](./docs/DOCS.md) | [Examples](./examples/) | [Report Issue](https://github.com/ROHIT8759/rkk-next/issues)
-
-NPM publish
-
-If you want, I can now:
-
-✔ Review this README
-
-✔ Add badges (npm, downloads)
-
-✔ Prepare NPM publish checklist
-
-✔ Create example Next.js app
-
-✔ Final SDK audit before release
-
-Just tell me 👍

package/dist/analytics/webVitals.d.ts

@@ -1,2 +1,66 @@
 import { NextWebVitalsMetric } from "next/app";
+export type VitalsReporter = (metric: WebVitalPayload) => void | Promise<void>;
+export interface WebVitalPayload {
+    id: string;
+    name: string;
+    value: number;
+    rating: "good" | "needs-improvement" | "poor";
+    delta: number;
+    navigationType: string;
+    label: "web-vital" | "custom";
+}
+export interface WebVitalsOptions {
+    /**
+     * Send metrics to a custom analytics endpoint via POST.
+     * The payload is a JSON body matching WebVitalPayload.
+     */
+    endpoint?: string;
+    /**
+     * Google Analytics measurement ID (e.g. "G-XXXXXXXXXX" or "UA-XXXXXXX-X").
+     * Requires window.gtag to be loaded.
+     */
+    gaMeasurementId?: string;
+    /**
+     * Custom reporter function for full control.
+     * Called for every metric after built-in reporters.
+     */
+    reporter?: VitalsReporter;
+    /**
+     * Log metrics to the console (useful during development).
+     * Defaults to true in development, false in production.
+     */
+    debug?: boolean;
+    /**
+     * Batch endpoint sends — queue metrics and flush on page unload.
+     * Only relevant when `endpoint` is set.
+     * @default false
+     */
+    batch?: boolean;
+    /**
+     * Flush interval in milliseconds when batching is enabled.
+     * @default 5000
+     */
+    flushIntervalMs?: number;
+}
+/**
+ * Creates a configured `reportWebVitals` function ready to drop into
+ * `pages/_app.tsx` (or `app/layout.tsx` via useReportWebVitals hook).
+ *
+ * @example
+ * // pages/_app.tsx
+ * export const reportWebVitals = createWebVitalsReporter({
+ *   endpoint: "/api/vitals",
+ *   gaMeasurementId: "G-XXXXXXXXXX",
+ *   debug: true,
+ * });
+ */
+export declare function createWebVitalsReporter(options?: WebVitalsOptions): (metric: NextWebVitalsMetric) => void;
+/**
+ * Simple drop-in reporter that logs to console.
+ * For production use, prefer `createWebVitalsReporter` with options.
+ *
+ * @example
+ * // pages/_app.tsx
+ * export { reportWebVitals } from "rkk-next";
+ */
 export declare function reportWebVitals(metric: NextWebVitalsMetric): void;

package/dist/analytics/webVitals.js

@@ -1,8 +1,163 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebVitalsReporter = createWebVitalsReporter;
 exports.reportWebVitals = reportWebVitals;
+/** Map raw CWV value to a rating bucket */
+function getRating(name, value) {
+    const thresholds = {
+        LCP: [2500, 4000],
+        FID: [100, 300],
+        CLS: [0.1, 0.25],
+        INP: [200, 500],
+        TTFB: [800, 1800],
+        FCP: [1800, 3000],
+    };
+    const t = thresholds[name];
+    if (!t)
+        return "good";
+    if (value <= t[0])
+        return "good";
+    if (value <= t[1])
+        return "needs-improvement";
+    return "poor";
+}
+/** Build a normalised payload from the Next.js metric object */
+function buildPayload(metric) {
+    var _a, _b, _c;
+    return {
+        id: metric.id,
+        name: metric.name,
+        value: metric.value,
+        delta: (_a = metric.delta) !== null && _a !== void 0 ? _a : metric.value,
+        navigationType: (_b = metric.navigationType) !== null && _b !== void 0 ? _b : "navigate",
+        label: (_c = metric.label) !== null && _c !== void 0 ? _c : "web-vital",
+        rating: getRating(metric.name, metric.value),
+    };
+}
+// Internal batch queue (used when batch:true)
+let _queue = [];
+let _batchEndpoint = null;
+let _flushScheduled = false;
+let _batchListenersAttached = false;
+let _flushTimer = null;
+function scheduleBatchFlush() {
+    if (_flushScheduled)
+        return;
+    _flushScheduled = true;
+    const flush = () => {
+        if (_queue.length === 0 || !_batchEndpoint) {
+            return;
+        }
+        const payload = [..._queue];
+        _queue = [];
+        // Use sendBeacon so the request survives page unload
+        if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+            navigator.sendBeacon(_batchEndpoint, JSON.stringify(payload));
+        }
+        else {
+            fetch(_batchEndpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(payload),
+                keepalive: true,
+            }).catch(() => { });
+        }
+    };
+    if (typeof window !== "undefined" && !_batchListenersAttached) {
+        _batchListenersAttached = true;
+        window.addEventListener("visibilitychange", () => {
+            if (document.visibilityState === "hidden")
+                flush();
+        });
+        window.addEventListener("pagehide", flush);
+    }
+}
+/**
+ * Creates a configured `reportWebVitals` function ready to drop into
+ * `pages/_app.tsx` (or `app/layout.tsx` via useReportWebVitals hook).
+ *
+ * @example
+ * // pages/_app.tsx
+ * export const reportWebVitals = createWebVitalsReporter({
+ *   endpoint: "/api/vitals",
+ *   gaMeasurementId: "G-XXXXXXXXXX",
+ *   debug: true,
+ * });
+ */
+function createWebVitalsReporter(options = {}) {
+    var _a;
+    const { endpoint = process.env.NEXT_PUBLIC_RKK_ANALYTICS_ENDPOINT ||
+        process.env.RKK_ANALYTICS_ENDPOINT, gaMeasurementId, reporter, debug = process.env.NODE_ENV === "development", batch = false, flushIntervalMs = 5000, } = options;
+    if (batch && endpoint) {
+        _batchEndpoint = endpoint;
+        scheduleBatchFlush();
+        if (!_flushTimer && flushIntervalMs > 0) {
+            _flushTimer = setInterval(() => {
+                if (_queue.length === 0 || !_batchEndpoint)
+                    return;
+                const payload = [..._queue];
+                _queue = [];
+                fetch(_batchEndpoint, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(payload),
+                    keepalive: true,
+                }).catch(() => { });
+            }, flushIntervalMs);
+            const timerWithUnref = _flushTimer;
+            (_a = timerWithUnref.unref) === null || _a === void 0 ? void 0 : _a.call(timerWithUnref);
+        }
+    }
+    return function reportWebVitals(metric) {
+        const payload = buildPayload(metric);
+        // 1. Debug logging
+        if (debug) {
+            const emoji = payload.rating === "good"
+                ? "✅"
+                : payload.rating === "needs-improvement"
+                    ? "⚠️"
+                    : "❌";
+            console.log(`[Vitals] ${emoji} ${payload.name} = ${payload.value.toFixed(1)} (${payload.rating})`);
+        }
+        // 2. Google Analytics (gtag)
+        if (gaMeasurementId && typeof window !== "undefined" && window.gtag) {
+            window.gtag("event", payload.name, {
+                event_category: payload.label === "web-vital" ? "Web Vitals" : "Custom Metric",
+                event_label: payload.id,
+                value: Math.round(payload.name === "CLS" ? payload.value * 1000 : payload.value),
+                non_interaction: true,
+                send_to: gaMeasurementId,
+            });
+        }
+        // 3. Custom endpoint
+        if (endpoint) {
+            if (batch) {
+                _queue.push(payload);
+            }
+            else {
+                fetch(endpoint, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(payload),
+                    keepalive: true,
+                }).catch(() => { });
+            }
+        }
+        // 4. Custom reporter callback
+        if (reporter) {
+            reporter(payload);
+        }
+    };
+}
+/**
+ * Simple drop-in reporter that logs to console.
+ * For production use, prefer `createWebVitalsReporter` with options.
+ *
+ * @example
+ * // pages/_app.tsx
+ * export { reportWebVitals } from "rkk-next";
+ */
 function reportWebVitals(metric) {
-    const { id, name, value } = metric;
-    console.log("[Vitals]", name, value);
-    // future: send to analytics
+    const payload = buildPayload(metric);
+    console.log("[Vitals]", payload.name, payload.value, `(${payload.rating})`);
 }

package/dist/backend/cache.d.ts

@@ -6,6 +6,14 @@ export interface CacheOptions {
     keyGenerator?: (req: NextApiRequest) => string;
     /** Conditional caching based on request */
     shouldCache?: (req: NextApiRequest) => boolean;
+    /** Optional adapter key namespace prefix */
+    namespace?: string;
+}
+export interface ExternalCacheAdapter {
+    get<T = any>(key: string): Promise<T | null>;
+    set<T = any>(key: string, data: T, ttlSeconds: number): Promise<void>;
+    delete?(key: string): Promise<void>;
+    clear?(): Promise<void>;
 }
 /**
  * In-memory cache store for API responses
@@ -18,18 +26,37 @@ declare class MemoryCache {
     delete(key: string): void;
     clear(): void;
     size(): number;
+    /** Return all live (non-expired) keys */
+    keys(): string[];
     /**
      * Clean up expired entries
      */
     cleanup(): void;
 }
 export declare const cache: MemoryCache;
+export declare function setCacheAdapter(adapter: ExternalCacheAdapter): void;
+export declare function clearCacheAdapter(): void;
+/**
+ * Create an adapter from common Redis-like clients.
+ * Supports clients exposing get/setEx/del or get/set with EX arg.
+ */
+export declare function createRedisCacheAdapter(client: {
+    get: (key: string) => Promise<string | null>;
+    setEx?: (key: string, ttl: number, value: string) => Promise<unknown>;
+    set?: (key: string, value: string, mode?: string, ttl?: number) => Promise<unknown>;
+    del?: (key: string) => Promise<unknown>;
+}): ExternalCacheAdapter;
 /**
  * Cache API response middleware
  */
 export declare function cacheResponse(options?: CacheOptions): (req: NextApiRequest, res: NextApiResponse, next: () => void | Promise<void>) => Promise<void>;
 /**
- * Invalidate cache by pattern or specific key
+ * Invalidate cache entries matching a pattern or an exact key.
+ *
+ * - No argument / undefined → clears the entire cache
+ * - string that is an exact key → removes that key only
+ * - string with regex metacharacters → treated as a regex pattern
+ * - RegExp → matched against every live key
  */
 export declare function invalidateCache(pattern?: string | RegExp): void;
 /**

package/dist/backend/cache.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cache = void 0;
+exports.setCacheAdapter = setCacheAdapter;
+exports.clearCacheAdapter = clearCacheAdapter;
+exports.createRedisCacheAdapter = createRedisCacheAdapter;
 exports.cacheResponse = cacheResponse;
 exports.invalidateCache = invalidateCache;
 exports.getCacheStats = getCacheStats;
@@ -43,6 +46,17 @@ class MemoryCache {
     size() {
         return this.cache.size;
     }
+    /** Return all live (non-expired) keys */
+    keys() {
+        const now = Date.now();
+        const result = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp <= entry.ttl) {
+                result.push(key);
+            }
+        }
+        return result;
+    }
     /**
      * Clean up expired entries
      */
@@ -56,6 +70,48 @@ class MemoryCache {
     }
 }
 exports.cache = new MemoryCache();
+let externalCacheAdapter = null;
+function setCacheAdapter(adapter) {
+    externalCacheAdapter = adapter;
+}
+function clearCacheAdapter() {
+    externalCacheAdapter = null;
+}
+/**
+ * Create an adapter from common Redis-like clients.
+ * Supports clients exposing get/setEx/del or get/set with EX arg.
+ */
+function createRedisCacheAdapter(client) {
+    return {
+        async get(key) {
+            const value = await client.get(key);
+            if (!value) {
+                return null;
+            }
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return null;
+            }
+        },
+        async set(key, data, ttlSeconds) {
+            const payload = JSON.stringify(data);
+            if (client.setEx) {
+                await client.setEx(key, ttlSeconds, payload);
+                return;
+            }
+            if (client.set) {
+                await client.set(key, payload, 'EX', ttlSeconds);
+            }
+        },
+        async delete(key) {
+            if (client.del) {
+                await client.del(key);
+            }
+        },
+    };
+}
 // Periodic cleanup every 5 minutes
 if (typeof setInterval !== 'undefined') {
     setInterval(() => exports.cache.cleanup(), 5 * 60 * 1000);
@@ -74,7 +130,7 @@ function defaultKeyGenerator(req) {
  */
 function cacheResponse(options = {}) {
     const { ttl = 60, // Default 60 seconds
-    keyGenerator = defaultKeyGenerator, shouldCache = (req) => req.method === 'GET', } = options;
+    keyGenerator = defaultKeyGenerator, shouldCache = (req) => req.method === 'GET', namespace = 'rkk-next', } = options;
     return async (req, res, next) => {
         // Skip caching if condition not met
         if (!shouldCache(req)) {
@@ -82,10 +138,23 @@ function cacheResponse(options = {}) {
             return;
         }
         const cacheKey = keyGenerator(req);
+        const adapterKey = `${namespace}:${cacheKey}`;
+        // Optional external adapter first (e.g. Redis)
+        if (externalCacheAdapter) {
+            const adapted = await externalCacheAdapter.get(adapterKey);
+            if (adapted) {
+                res.setHeader('X-Cache', 'HIT');
+                res.setHeader('X-Cache-Provider', 'adapter');
+                res.setHeader('Cache-Control', `public, max-age=${ttl}`);
+                res.status(200).json(adapted);
+                return;
+            }
+        }
         // Check if cached response exists
         const cachedData = exports.cache.get(cacheKey);
         if (cachedData) {
             res.setHeader('X-Cache', 'HIT');
+            res.setHeader('X-Cache-Provider', 'memory');
             res.setHeader('Cache-Control', `public, max-age=${ttl}`);
             res.status(200).json(cachedData);
             return;
@@ -108,7 +177,13 @@ function cacheResponse(options = {}) {
             if (res.statusCode >= 200 && res.statusCode < 300 && responseData) {
                 exports.cache.set(cacheKey, responseData, ttl);
                 res.setHeader('X-Cache', 'MISS');
+                res.setHeader('X-Cache-Provider', 'memory');
                 res.setHeader('Cache-Control', `public, max-age=${ttl}`);
+                if (externalCacheAdapter) {
+                    externalCacheAdapter.set(adapterKey, responseData, ttl).catch(() => {
+                        // Ignore adapter write errors and keep request successful.
+                    });
+                }
             }
             return originalEnd.apply(this, args);
         };
@@ -116,19 +191,26 @@ function cacheResponse(options = {}) {
     };
 }
 /**
- * Invalidate cache by pattern or specific key
+ * Invalidate cache entries matching a pattern or an exact key.
+ *
+ * - No argument / undefined → clears the entire cache
+ * - string that is an exact key → removes that key only
+ * - string with regex metacharacters → treated as a regex pattern
+ * - RegExp → matched against every live key
  */
 function invalidateCache(pattern) {
     if (!pattern) {
         exports.cache.clear();
+        if (externalCacheAdapter === null || externalCacheAdapter === void 0 ? void 0 : externalCacheAdapter.clear) {
+            externalCacheAdapter.clear().catch(() => {
+                // noop
+            });
+        }
         return;
     }
-    const regex = typeof pattern === 'string'
-        ? new RegExp(pattern)
-        : pattern;
-    // This is a simplified implementation
-    // In production, you'd want a more efficient pattern matching
-    exports.cache.clear(); // For now, clear all
+    const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+    const matched = exports.cache.keys().filter((key) => regex.test(key));
+    matched.forEach((key) => exports.cache.delete(key));
 }
 /**
  * Get cache statistics

package/dist/backend/middleware.d.ts

@@ -1,6 +1,18 @@
 import { NextApiRequest, NextApiResponse } from 'next';
 export type NextApiHandler = (req: NextApiRequest, res: NextApiResponse) => Promise<void> | void;
 export type Middleware = (req: NextApiRequest, res: NextApiResponse, next: () => void | Promise<void>) => void | Promise<void>;
+type ValidationResult = boolean | string | {
+    valid: boolean;
+    message?: string;
+    details?: unknown;
+};
+type FieldValidator = (data: any, req?: NextApiRequest) => ValidationResult | Promise<ValidationResult>;
+type RequestValidator = (req: NextApiRequest) => ValidationResult | Promise<ValidationResult>;
+export declare class HttpError extends Error {
+    statusCode: number;
+    details?: unknown;
+    constructor(message: string, statusCode?: number, details?: unknown);
+}
 /**
  * Compose multiple middleware functions into a single handler
  */
@@ -21,15 +33,20 @@ export declare function rateLimit(options?: {
     windowMs?: number;
     max?: number;
     message?: string;
+    cleanupIntervalMs?: number;
 }): Middleware;
 /**
  * Request validation middleware
  */
 export declare function validateRequest(schema: {
-    body?: (data: any) => boolean;
-    query?: (data: any) => boolean;
-    headers?: (data: any) => boolean;
-}): Middleware;
+    body?: FieldValidator;
+    query?: FieldValidator;
+    headers?: FieldValidator;
+} | RequestValidator): Middleware;
+/**
+ * Request timeout middleware
+ */
+export declare function requestTimeout(ms?: number): Middleware;
 /**
  * Request logging middleware
  */
@@ -41,3 +58,4 @@ export declare function logger(options?: {
  * Error handling middleware
  */
 export declare function errorHandler(): Middleware;
+export {};

package/dist/backend/middleware.js

@@ -1,11 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = void 0;
 exports.composeMiddleware = composeMiddleware;
 exports.cors = cors;
 exports.rateLimit = rateLimit;
 exports.validateRequest = validateRequest;
+exports.requestTimeout = requestTimeout;
 exports.logger = logger;
 exports.errorHandler = errorHandler;
+function normalizeValidationResult(result) {
+    if (typeof result === 'boolean') {
+        return { isValid: result };
+    }
+    if (typeof result === 'string') {
+        return { isValid: false, message: result };
+    }
+    return {
+        isValid: result.valid,
+        message: result.message,
+        details: result.details,
+    };
+}
+class HttpError extends Error {
+    constructor(message, statusCode = 500, details) {
+        super(message);
+        this.name = 'HttpError';
+        this.statusCode = statusCode;
+        this.details = details;
+    }
+}
+exports.HttpError = HttpError;
 /**
  * Compose multiple middleware functions into a single handler
  */
@@ -14,12 +38,17 @@ function composeMiddleware(...middlewares) {
         return async (req, res) => {
             let index = 0;
             const next = async () => {
+                if (res.writableEnded) {
+                    return;
+                }
                 if (index < middlewares.length) {
                     const middleware = middlewares[index++];
                     await middleware(req, res, next);
                 }
                 else {
-                    await handler(req, res);
+                    if (!res.writableEnded) {
+                        await handler(req, res);
+                    }
                 }
             };
             await next();
@@ -60,10 +89,13 @@ function cors(options = {}) {
 function rateLimit(options = {}) {
     const { windowMs = 60000, // 1 minute
     max = 60, // 60 requests per minute
-    message = 'Too many requests, please try again later.', } = options;
+    message = 'Too many requests, please try again later.', cleanupIntervalMs = windowMs, } = options;
     const requests = new Map();
+    let lastCleanupAt = Date.now();
     return (req, res, next) => {
-        const identifier = req.headers['x-forwarded-for'] ||
+        var _a;
+        const forwarded = req.headers['x-forwarded-for'];
+        const identifier = (typeof forwarded === 'string' ? (_a = forwarded.split(',')[0]) === null || _a === void 0 ? void 0 : _a.trim() : '') ||
             req.socket.remoteAddress ||
             'unknown';
         const now = Date.now();
@@ -73,14 +105,23 @@ function rateLimit(options = {}) {
         // Filter out requests outside the time window
         userRequests = userRequests.filter(time => time > windowStart);
         if (userRequests.length >= max) {
+            const resetInSeconds = Math.max(1, Math.ceil((userRequests[0] + windowMs - now) / 1000));
+            res.setHeader('X-RateLimit-Limit', String(max));
+            res.setHeader('X-RateLimit-Remaining', '0');
+            res.setHeader('X-RateLimit-Reset', String(resetInSeconds));
             res.status(429).json({ error: message });
             return;
         }
         // Add current request
         userRequests.push(now);
         requests.set(identifier, userRequests);
-        // Cleanup old entries periodically
-        if (Math.random() < 0.01) {
+        const remaining = Math.max(0, max - userRequests.length);
+        res.setHeader('X-RateLimit-Limit', String(max));
+        res.setHeader('X-RateLimit-Remaining', String(remaining));
+        res.setHeader('X-RateLimit-Reset', String(Math.ceil(windowMs / 1000)));
+        // Deterministic cleanup to prevent unbounded growth
+        if (now - lastCleanupAt >= cleanupIntervalMs) {
+            lastCleanupAt = now;
             for (const [key, times] of requests.entries()) {
                 const filteredTimes = times.filter(time => time > windowStart);
                 if (filteredTimes.length === 0) {
@@ -98,24 +139,92 @@ function rateLimit(options = {}) {
  * Request validation middleware
  */
 function validateRequest(schema) {
-    return (req, res, next) => {
+    return async (req, res, next) => {
         try {
-            if (schema.body && !schema.body(req.body)) {
-                res.status(400).json({ error: 'Invalid request body' });
+            if (typeof schema === 'function') {
+                const result = normalizeValidationResult(await schema(req));
+                if (!result.isValid) {
+                    res.status(400).json({
+                        error: result.message || 'Validation failed',
+                        details: result.details,
+                    });
+                    return;
+                }
+                next();
                 return;
             }
-            if (schema.query && !schema.query(req.query)) {
-                res.status(400).json({ error: 'Invalid query parameters' });
-                return;
+            if (schema.body) {
+                const result = normalizeValidationResult(await schema.body(req.body, req));
+                if (!result.isValid) {
+                    res.status(400).json({
+                        error: result.message || 'Invalid request body',
+                        field: 'body',
+                        details: result.details,
+                    });
+                    return;
+                }
             }
-            if (schema.headers && !schema.headers(req.headers)) {
-                res.status(400).json({ error: 'Invalid headers' });
-                return;
+            if (schema.query) {
+                const result = normalizeValidationResult(await schema.query(req.query, req));
+                if (!result.isValid) {
+                    res.status(400).json({
+                        error: result.message || 'Invalid query parameters',
+                        field: 'query',
+                        details: result.details,
+                    });
+                    return;
+                }
+            }
+            if (schema.headers) {
+                const result = normalizeValidationResult(await schema.headers(req.headers, req));
+                if (!result.isValid) {
+                    res.status(400).json({
+                        error: result.message || 'Invalid headers',
+                        field: 'headers',
+                        details: result.details,
+                    });
+                    return;
+                }
             }
             next();
         }
         catch (error) {
-            res.status(400).json({ error: 'Validation error' });
+            const message = error instanceof Error ? error.message : 'Validation error';
+            res.status(400).json({ error: message });
+        }
+    };
+}
+/**
+ * Request timeout middleware
+ */
+function requestTimeout(ms = 30000) {
+    return async (req, res, next) => {
+        let timer;
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new HttpError(`Request timeout after ${ms}ms`, 408));
+            }, ms);
+        });
+        try {
+            await Promise.race([Promise.resolve(next()), timeoutPromise]);
+        }
+        catch (error) {
+            if (res.writableEnded) {
+                return;
+            }
+            if (error instanceof HttpError && error.statusCode === 408) {
+                res.status(408).json({
+                    error: 'Request timeout',
+                    message: error.message,
+                });
+                return;
+            }
+            throw error;
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
         }
     };
 }
@@ -171,12 +280,26 @@ function errorHandler() {
             await next();
         }
         catch (error) {
+            if (res.writableEnded) {
+                return;
+            }
             console.error('[API Error]', error);
             const isDev = process.env.NODE_ENV === 'development';
-            res.status(500).json({
-                error: 'Internal server error',
+            const statusCode = error instanceof HttpError
+                ? error.statusCode
+                : (typeof error === 'object' && error && 'statusCode' in error && typeof error.statusCode === 'number'
+                    ? error.statusCode
+                    : 500);
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            const details = error instanceof HttpError
+                ? error.details
+                : (typeof error === 'object' && error && 'details' in error ? error.details : undefined);
+            res.status(statusCode).json({
+                error: statusCode >= 500 ? 'Internal server error' : message,
+                ...(statusCode >= 500 ? undefined : { message }),
+                ...(details ? { details } : undefined),
                 ...(isDev && {
-                    message: error instanceof Error ? error.message : 'Unknown error',
+                    message,
                     stack: error instanceof Error ? error.stack : undefined
                 }),
             });

package/dist/performance/securityHeaders.d.ts

@@ -1,4 +1,16 @@
-export declare const SECURITY_HEADERS: {
+export type SecurityHeader = {
     key: string;
     value: string;
-}[];
+};
+export type SecurityHeadersOptions = {
+    csp?: string;
+    hsts?: string;
+    permissionsPolicy?: string;
+    includeCrossOriginPolicies?: boolean;
+};
+export declare function buildSecurityHeaders(options?: SecurityHeadersOptions): SecurityHeader[];
+export declare const SECURITY_HEADERS: SecurityHeader[];
+export declare const SECURITY_HEADER_PRESETS: {
+    STRICT: SecurityHeader[];
+    API_FRIENDLY: SecurityHeader[];
+};

package/dist/performance/securityHeaders.js

@@ -1,17 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SECURITY_HEADERS = void 0;
-exports.SECURITY_HEADERS = [
-    {
-        key: "X-Frame-Options",
-        value: "DENY",
-    },
-    {
-        key: "X-Content-Type-Options",
-        value: "nosniff",
-    },
-    {
-        key: "Referrer-Policy",
-        value: "strict-origin-when-cross-origin",
-    },
-];
+exports.SECURITY_HEADER_PRESETS = exports.SECURITY_HEADERS = void 0;
+exports.buildSecurityHeaders = buildSecurityHeaders;
+const DEFAULT_CSP = [
+    "default-src 'self'",
+    "script-src 'self' 'unsafe-inline'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: https:",
+    "font-src 'self' data:",
+    "connect-src 'self' https:",
+    "frame-ancestors 'none'",
+    "base-uri 'self'",
+    "form-action 'self'",
+].join('; ');
+const DEFAULT_HSTS = 'max-age=63072000; includeSubDomains; preload';
+const DEFAULT_PERMISSIONS_POLICY = [
+    'camera=()',
+    'microphone=()',
+    'geolocation=()',
+    'payment=()',
+    'usb=()',
+].join(', ');
+function buildSecurityHeaders(options = {}) {
+    const { csp = DEFAULT_CSP, hsts = DEFAULT_HSTS, permissionsPolicy = DEFAULT_PERMISSIONS_POLICY, includeCrossOriginPolicies = true, } = options;
+    const headers = [
+        {
+            key: 'X-Frame-Options',
+            value: 'DENY',
+        },
+        {
+            key: 'X-Content-Type-Options',
+            value: 'nosniff',
+        },
+        {
+            key: 'Referrer-Policy',
+            value: 'strict-origin-when-cross-origin',
+        },
+        {
+            key: 'Content-Security-Policy',
+            value: csp,
+        },
+        {
+            key: 'Strict-Transport-Security',
+            value: hsts,
+        },
+        {
+            key: 'Permissions-Policy',
+            value: permissionsPolicy,
+        },
+    ];
+    if (includeCrossOriginPolicies) {
+        headers.push({
+            key: 'Cross-Origin-Opener-Policy',
+            value: 'same-origin',
+        }, {
+            key: 'Cross-Origin-Resource-Policy',
+            value: 'same-origin',
+        });
+    }
+    return headers;
+}
+exports.SECURITY_HEADERS = buildSecurityHeaders();
+exports.SECURITY_HEADER_PRESETS = {
+    STRICT: buildSecurityHeaders(),
+    API_FRIENDLY: buildSecurityHeaders({
+        csp: "default-src 'none'; frame-ancestors 'none'; base-uri 'none'",
+        includeCrossOriginPolicies: false,
+    }),
+};

package/dist/routing/SmartLink.d.ts

@@ -1,17 +1,37 @@
 import { LinkProps } from "next/link";
 import React, { AnchorHTMLAttributes } from "react";
-type AnchorProps = AnchorHTMLAttributes<HTMLAnchorElement>;
-export type SmartLinkProps = LinkProps & AnchorProps & {
-    /** Enable intelligent prefetching */
+type AnchorProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href">;
+export type SmartLinkProps = Omit<LinkProps, "onMouseEnter"> & AnchorProps & {
+    /** Enable intelligent prefetching on hover */
     prefetchOnHover?: boolean;
-    /** Delay before prefetch (ms) */
+    /** Delay before prefetch starts (ms) */
     prefetchDelay?: number;
     /** Disable prefetch completely */
     disablePrefetch?: boolean;
+    /** Child content */
+    children?: React.ReactNode;
 };
 /**
  * SmartLink
- * SEO-safe, accessibility-friendly, and performance-optimized
+ *
+ * A drop-in replacement for Next.js `<Link>` that adds:
+ * - Intelligent hover-based route prefetching
+ * - Network-aware prefetch (skips on slow 2g/slow-2g)
+ * - Full TypeScript types, accessible, and SSR-safe
+ *
+ * Compatible with Next.js 13+ App Router and Pages Router.
+ *
+ * @example
+ * <SmartLink href="/blog">Read the blog</SmartLink>
  */
-export declare const SmartLink: React.FC<SmartLinkProps>;
+export declare const SmartLink: React.ForwardRefExoticComponent<Omit<LinkProps<any>, "onMouseEnter"> & AnchorProps & {
+    /** Enable intelligent prefetching on hover */
+    prefetchOnHover?: boolean;
+    /** Delay before prefetch starts (ms) */
+    prefetchDelay?: number;
+    /** Disable prefetch completely */
+    disablePrefetch?: boolean;
+    /** Child content */
+    children?: React.ReactNode;
+} & React.RefAttributes<HTMLAnchorElement>>;
 export default SmartLink;

package/dist/routing/SmartLink.js

@@ -42,21 +42,27 @@ const react_1 = __importStar(require("react"));
 const prefetch_1 = require("./prefetch");
 /**
  * SmartLink
- * SEO-safe, accessibility-friendly, and performance-optimized
+ *
+ * A drop-in replacement for Next.js `<Link>` that adds:
+ * - Intelligent hover-based route prefetching
+ * - Network-aware prefetch (skips on slow 2g/slow-2g)
+ * - Full TypeScript types, accessible, and SSR-safe
+ *
+ * Compatible with Next.js 13+ App Router and Pages Router.
+ *
+ * @example
+ * <SmartLink href="/blog">Read the blog</SmartLink>
  */
-const SmartLink = ({ href, children, prefetchOnHover = true, prefetchDelay = 150, disablePrefetch = false, onMouseEnter, ...props }) => {
+exports.SmartLink = react_1.default.forwardRef(({ href, children, prefetchOnHover = true, prefetchDelay = 150, disablePrefetch = false, onMouseEnter, ...props }, ref) => {
     const handleMouseEnter = (0, react_1.useCallback)((e) => {
         onMouseEnter === null || onMouseEnter === void 0 ? void 0 : onMouseEnter(e);
         if (disablePrefetch || !prefetchOnHover)
             return;
         if (typeof href === "string" && (0, prefetch_1.isFastConnection)()) {
-            (0, prefetch_1.prefetchRoute)(href, {
-                delay: prefetchDelay,
-            });
+            (0, prefetch_1.prefetchRoute)(href, { delay: prefetchDelay });
         }
     }, [href, disablePrefetch, prefetchOnHover, prefetchDelay, onMouseEnter]);
-    return (react_1.default.createElement(link_1.default, { href: href, passHref: true, legacyBehavior: true },
-        react_1.default.createElement("a", { ...props, onMouseEnter: handleMouseEnter }, children)));
-};
-exports.SmartLink = SmartLink;
+    return (react_1.default.createElement(link_1.default, { href: href, ...props, onMouseEnter: handleMouseEnter, ref: ref }, children));
+});
+exports.SmartLink.displayName = "SmartLink";
 exports.default = exports.SmartLink;

package/dist/seo/MetaManager.js

@@ -7,31 +7,64 @@ exports.MetaManager = void 0;
 const head_1 = __importDefault(require("next/head"));
 const router_1 = require("next/router");
 const react_1 = __importDefault(require("react"));
+function sanitizeText(input) {
+    if (typeof input !== "string")
+        return undefined;
+    return input
+        .replace(/[\u0000-\u001F\u007F]/g, "")
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;")
+        .trim();
+}
+function sanitizeUrl(input) {
+    if (typeof input !== "string" || !input.trim())
+        return undefined;
+    const raw = input.trim();
+    if (/^javascript:/i.test(raw) || /^data:/i.test(raw)) {
+        return undefined;
+    }
+    return raw;
+}
+function sanitizeTwitterHandle(handle) {
+    if (!handle)
+        return undefined;
+    return handle.replace(/^@+/, "").replace(/[^a-zA-Z0-9_]/g, "");
+}
 const MetaManager = ({ title, description, keywords, canonicalUrl, image, type = "website", noIndex = false, siteName = "My Website", author, twitterHandle, }) => {
     const router = (0, router_1.useRouter)();
+    const safeTitle = sanitizeText(title) || "";
+    const safeDescription = sanitizeText(description) || "";
+    const safeKeywords = sanitizeText(keywords);
+    const safeAuthor = sanitizeText(author);
+    const safeSiteName = sanitizeText(siteName) || "My Website";
+    const safeImage = sanitizeUrl(image);
+    const safeTwitterHandle = sanitizeTwitterHandle(twitterHandle);
     // Auto canonical URL fallback
-    const canonical = canonicalUrl ||
+    const canonical = sanitizeUrl(canonicalUrl ||
         (typeof window !== "undefined"
             ? `${window.location.origin}${router.asPath}`
-            : "");
+            : ""));
     return (react_1.default.createElement(head_1.default, null,
-        react_1.default.createElement("title", null, title),
-        react_1.default.createElement("meta", { name: "description", content: description }),
-        keywords && react_1.default.createElement("meta", { name: "keywords", content: keywords }),
-        author && react_1.default.createElement("meta", { name: "author", content: author }),
+        react_1.default.createElement("title", null, safeTitle),
+        react_1.default.createElement("meta", { name: "description", content: safeDescription }),
+        safeKeywords && react_1.default.createElement("meta", { name: "keywords", content: safeKeywords }),
+        safeAuthor && react_1.default.createElement("meta", { name: "author", content: safeAuthor }),
         react_1.default.createElement("meta", { name: "robots", content: noIndex ? "noindex, nofollow" : "index, follow" }),
         canonical && react_1.default.createElement("link", { rel: "canonical", href: canonical }),
         react_1.default.createElement("meta", { property: "og:type", content: type }),
-        react_1.default.createElement("meta", { property: "og:title", content: title }),
-        react_1.default.createElement("meta", { property: "og:description", content: description }),
-        react_1.default.createElement("meta", { property: "og:site_name", content: siteName }),
+        react_1.default.createElement("meta", { property: "og:title", content: safeTitle }),
+        react_1.default.createElement("meta", { property: "og:description", content: safeDescription }),
+        react_1.default.createElement("meta", { property: "og:site_name", content: safeSiteName }),
         canonical && react_1.default.createElement("meta", { property: "og:url", content: canonical }),
-        image && react_1.default.createElement("meta", { property: "og:image", content: image }),
+        safeImage && react_1.default.createElement("meta", { property: "og:image", content: safeImage }),
         react_1.default.createElement("meta", { name: "twitter:card", content: "summary_large_image" }),
-        twitterHandle && (react_1.default.createElement("meta", { name: "twitter:site", content: `@${twitterHandle}` })),
-        react_1.default.createElement("meta", { name: "twitter:title", content: title }),
-        react_1.default.createElement("meta", { name: "twitter:description", content: description }),
-        image && react_1.default.createElement("meta", { name: "twitter:image", content: image }),
+        safeTwitterHandle && (react_1.default.createElement("meta", { name: "twitter:site", content: `@${safeTwitterHandle}` })),
+        react_1.default.createElement("meta", { name: "twitter:title", content: safeTitle }),
+        react_1.default.createElement("meta", { name: "twitter:description", content: safeDescription }),
+        safeImage && react_1.default.createElement("meta", { name: "twitter:image", content: safeImage }),
         react_1.default.createElement("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }),
         react_1.default.createElement("meta", { name: "theme-color", content: "#000000" })));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rkk-next",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "SEO, routing, performance optimization and backend utilities SDK for Next.js",
   "author": "Rohit Kumar Kundu",
   "license": "MIT",
@@ -25,10 +25,13 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "test:e2e": "jest __tests__/e2e",
+    "test:cli": "jest --config cli/jest.config.js",
+    "test:ci": "npm run test:coverage && npm run test:e2e && npm run test:cli",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "next": ">=12",
+    "next": ">=14 <16",
     "react": ">=17",
     "react-dom": ">=17"
   },