@revealui/cache 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025-2026 RevealUI Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/LICENSE.commercial

@@ -0,0 +1,111 @@
+RevealUI Commercial License
+Version 1.0, February 2026
+
+Copyright (c) 2025-2026 RevealUI Studio (founder@revealui.com)
+
+TERMS AND CONDITIONS
+
+1. DEFINITIONS
+
+"Software" means the RevealUI source code, documentation, and associated
+files contained in directories and packages designated as commercial,
+including but not limited to: packages/ai, packages/harnesses, and any
+directory named "ee" within the repository.
+
+"License Key" means a valid RevealUI license key obtained through an active
+paid subscription at https://revealui.com.
+
+"Licensee" means the individual or organization that holds a valid License
+Key through an active subscription.
+
+"Production Use" means any use of the Software beyond local development and
+evaluation, including but not limited to: deploying the Software to serve
+end users, integrating the Software into a product or service, or using the
+Software in a revenue-generating capacity.
+
+2. GRANT OF RIGHTS
+
+Subject to the terms of this License and a valid License Key, the Licensee
+is granted a non-exclusive, non-transferable, revocable license to:
+
+  (a) Use the Software for internal development and Production Use.
+  (b) Modify the Software for internal use.
+  (c) Deploy the Software on infrastructure controlled by the Licensee.
+
+Enterprise License holders are additionally granted the right to:
+
+  (d) Deploy the Software in a self-hosted environment.
+  (e) Remove or replace RevealUI branding (white-label).
+  (f) Use the Software for multiple tenants within the Licensee's
+      organization or customer base.
+
+3. RESTRICTIONS
+
+The Licensee SHALL NOT:
+
+  (a) Provide the Software, or any portion of it, to third parties as a
+      hosted or managed service that competes with RevealUI.
+  (b) Redistribute, sublicense, sell, or otherwise transfer the Software
+      or any portion of it to third parties.
+  (c) Remove, alter, or circumvent the license key verification
+      functionality of the Software.
+  (d) Use the Software in Production without a valid License Key.
+  (e) Share, publish, or make the License Key available to unauthorized
+      parties.
+
+4. EVALUATION
+
+The Software may be used for evaluation and local development purposes
+without a License Key. Evaluation use does not grant any rights to
+Production Use.
+
+5. SUBSCRIPTION AND PAYMENT
+
+This License is valid only during the term of an active paid subscription.
+Upon cancellation or expiration of the subscription:
+
+  (a) The License terminates automatically.
+  (b) A grace period of fourteen (14) days is provided for the Licensee
+      to transition away from Production Use.
+  (c) After the grace period, the Licensee must cease all Production Use
+      of the Software.
+
+6. INTELLECTUAL PROPERTY
+
+The Software is and remains the intellectual property of RevealUI Studio.
+This License does not grant any ownership rights. Contributions to
+commercial portions of the Software require a Contributor License Agreement.
+
+7. OPEN SOURCE COMPONENTS
+
+This License applies only to files and directories designated as commercial.
+Files under the MIT License (as indicated in the root LICENSE file) are not
+subject to this commercial license and may be used freely under MIT terms.
+
+8. DISCLAIMER OF WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+9. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL REVEALUI STUDIO BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE, EXCEEDING THE AMOUNT PAID BY THE LICENSEE IN
+THE TWELVE (12) MONTHS PRECEDING THE CLAIM.
+
+10. GOVERNING LAW
+
+This License shall be governed by the laws of the State of California,
+United States of America, without regard to its conflict of law provisions.
+
+11. ENTIRE AGREEMENT
+
+This License constitutes the entire agreement between the parties with
+respect to the commercial portions of the Software and supersedes all
+prior agreements, understandings, and communications.
+
+For licensing inquiries: founder@revealui.com
+For pricing and subscriptions: https://revealui.com/pricing

package/dist/index.d.ts

@@ -0,0 +1,366 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * CDN Configuration and Cache Management
+ *
+ * Utilities for CDN caching, edge caching, and cache invalidation
+ */
+/**
+ * CDN Cache Configuration
+ */
+interface CDNCacheConfig {
+    provider?: 'cloudflare' | 'vercel' | 'fastly' | 'custom';
+    zones?: string[];
+    ttl?: number;
+    staleWhileRevalidate?: number;
+    staleIfError?: number;
+    bypassCache?: boolean;
+    cacheKey?: string[];
+    varyHeaders?: string[];
+}
+declare const DEFAULT_CDN_CONFIG: CDNCacheConfig;
+/**
+ * Generate Cache-Control header
+ */
+declare function generateCacheControl(config: {
+    maxAge?: number;
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+    staleIfError?: number;
+    public?: boolean;
+    private?: boolean;
+    immutable?: boolean;
+    noCache?: boolean;
+    noStore?: boolean;
+}): string;
+/**
+ * Cache presets for different asset types
+ */
+declare const CDN_CACHE_PRESETS: {
+    readonly immutable: {
+        readonly maxAge: 31536000;
+        readonly sMaxAge: 31536000;
+        readonly public: true;
+        readonly immutable: true;
+    };
+    readonly static: {
+        readonly maxAge: 2592000;
+        readonly sMaxAge: 31536000;
+        readonly staleWhileRevalidate: 86400;
+        readonly public: true;
+    };
+    readonly api: {
+        readonly maxAge: 0;
+        readonly sMaxAge: 60;
+        readonly staleWhileRevalidate: 30;
+        readonly public: true;
+    };
+    readonly page: {
+        readonly maxAge: 0;
+        readonly sMaxAge: 300;
+        readonly staleWhileRevalidate: 60;
+        readonly public: true;
+    };
+    readonly private: {
+        readonly maxAge: 300;
+        readonly private: true;
+        readonly staleWhileRevalidate: 60;
+    };
+    readonly noCache: {
+        readonly noStore: true;
+    };
+    readonly revalidate: {
+        readonly maxAge: 0;
+        readonly sMaxAge: 0;
+        readonly noCache: true;
+    };
+};
+/**
+ * CDN Purge Configuration
+ */
+interface CDNPurgeConfig {
+    provider: 'cloudflare' | 'vercel' | 'fastly';
+    apiKey?: string;
+    apiSecret?: string;
+    zoneId?: string;
+    distributionId?: string;
+}
+/**
+ * Purge CDN cache
+ */
+declare function purgeCDNCache(urls: string[], config: CDNPurgeConfig): Promise<{
+    success: boolean;
+    purged: number;
+    errors?: string[];
+}>;
+/**
+ * Purge by cache tag
+ */
+declare function purgeCacheByTag(tags: string[], config: CDNPurgeConfig): Promise<{
+    success: boolean;
+    purged: number;
+    errors?: string[];
+}>;
+/**
+ * Purge everything
+ */
+declare function purgeAllCache(config: CDNPurgeConfig): Promise<{
+    success: boolean;
+    errors?: string[];
+}>;
+/**
+ * CDN cache warming
+ */
+declare function warmCDNCache(urls: string[], options?: {
+    concurrency?: number;
+    headers?: Record<string, string>;
+}): Promise<{
+    warmed: number;
+    failed: number;
+    errors: string[];
+}>;
+/**
+ * Generate cache tags
+ */
+declare function generateCacheTags(resource: {
+    type: string;
+    id?: string | number;
+    related?: string[];
+}): string[];
+/**
+ * Edge cache configuration for Vercel
+ */
+declare function generateVercelCacheConfig(preset: keyof typeof CDN_CACHE_PRESETS): {
+    headers: {
+        'Cache-Control': string;
+        'CDN-Cache-Control': string;
+        'Vercel-CDN-Cache-Control': string;
+    };
+};
+/**
+ * Edge cache configuration for Cloudflare
+ */
+declare function generateCloudflareConfig(preset: keyof typeof CDN_CACHE_PRESETS, options?: {
+    cacheTags?: string[];
+    bypassOnCookie?: string;
+}): {
+    headers: Record<string, string>;
+};
+/**
+ * Check if response should be cached
+ */
+declare function shouldCacheResponse(status: number, headers: Headers): boolean;
+/**
+ * Calculate cache TTL from headers
+ */
+declare function getCacheTTL(headers: Headers): number;
+
+/**
+ * Edge Caching and ISR (Incremental Static Regeneration)
+ *
+ * Utilities for Next.js edge caching, ISR, and on-demand revalidation
+ */
+
+/**
+ * Next.js extends the standard RequestInit with a `next` property
+ * for ISR revalidation and cache tags.
+ */
+interface NextFetchRequestInit extends RequestInit {
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+}
+/**
+ * ISR Configuration
+ */
+interface ISRConfig {
+    revalidate?: number | false;
+    tags?: string[];
+    dynamicParams?: boolean;
+}
+declare const ISR_PRESETS: {
+    readonly always: {
+        readonly revalidate: 0;
+    };
+    readonly minute: {
+        readonly revalidate: 60;
+    };
+    readonly fiveMinutes: {
+        readonly revalidate: 300;
+    };
+    readonly hourly: {
+        readonly revalidate: 3600;
+    };
+    readonly daily: {
+        readonly revalidate: 86400;
+    };
+    readonly never: {
+        readonly revalidate: false;
+    };
+};
+/**
+ * Generate static params for ISR
+ */
+declare function generateStaticParams<T>(fetchFn: () => Promise<T[]>, mapFn: (item: T) => Record<string, string>): Promise<Array<Record<string, string>>>;
+/**
+ * Revalidate tag
+ */
+declare function revalidateTag(tag: string, secret?: string): Promise<{
+    revalidated: boolean;
+    error?: string;
+}>;
+/**
+ * Revalidate path
+ */
+declare function revalidatePath(path: string, secret?: string): Promise<{
+    revalidated: boolean;
+    error?: string;
+}>;
+/**
+ * Revalidate multiple paths
+ */
+declare function revalidatePaths(paths: string[], secret?: string): Promise<{
+    revalidated: number;
+    failed: number;
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}>;
+/**
+ * Revalidate multiple tags
+ */
+declare function revalidateTags(tags: string[], secret?: string): Promise<{
+    revalidated: number;
+    failed: number;
+    errors: Array<{
+        tag: string;
+        error: string;
+    }>;
+}>;
+/**
+ * Edge middleware cache configuration
+ */
+interface EdgeCacheConfig {
+    cache?: 'force-cache' | 'no-cache' | 'no-store' | 'only-if-cached';
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+}
+/**
+ * Create edge cached fetch
+ */
+declare function createEdgeCachedFetch(config?: EdgeCacheConfig): <T>(url: string, options?: NextFetchRequestInit) => Promise<T>;
+/**
+ * Unstable cache wrapper (Next.js 14+)
+ */
+declare function createCachedFunction<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options?: {
+    tags?: string[];
+    revalidate?: number | false;
+}): (...args: TArgs) => Promise<TReturn>;
+/**
+ * Edge rate limiting with cache
+ */
+interface EdgeRateLimitConfig {
+    limit: number;
+    window: number;
+    key?: (request: NextRequest) => string;
+}
+declare class EdgeRateLimiter {
+    private config;
+    private cache;
+    constructor(config: EdgeRateLimitConfig);
+    /**
+     * Check rate limit
+     */
+    check(request: NextRequest): {
+        allowed: boolean;
+        limit: number;
+        remaining: number;
+        reset: number;
+    };
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): void;
+}
+/**
+ * Edge geolocation caching
+ */
+interface GeoLocation {
+    country?: string;
+    region?: string;
+    city?: string;
+    latitude?: number;
+    longitude?: number;
+}
+declare function getGeoLocation(request: NextRequest): GeoLocation | null;
+/**
+ * Edge A/B testing with cache
+ */
+declare function getABTestVariant(request: NextRequest, testName: string, variants: string[]): string;
+/**
+ * Edge personalization cache
+ */
+interface PersonalizationConfig {
+    userId?: string;
+    preferences?: Record<string, unknown>;
+    location?: GeoLocation;
+    device?: 'mobile' | 'tablet' | 'desktop';
+    variant?: string;
+}
+declare function getPersonalizationConfig(request: NextRequest): PersonalizationConfig;
+/**
+ * Edge cache headers helper
+ */
+declare function setEdgeCacheHeaders(response: NextResponse, config: {
+    maxAge?: number;
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+    tags?: string[];
+}): NextResponse;
+/**
+ * Preload links for critical resources
+ */
+declare function addPreloadLinks(response: NextResponse, resources: Array<{
+    href: string;
+    as: string;
+    type?: string;
+    crossorigin?: boolean;
+}>): NextResponse;
+/**
+ * Cache warming for ISR pages
+ */
+declare function warmISRCache(paths: string[], baseURL?: string): Promise<{
+    warmed: number;
+    failed: number;
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}>;
+
+/**
+ * Internal logger for @revealui/cache.
+ *
+ * Defaults to `console`. Consumers should call `configureCacheLogger()`
+ * to supply a structured logger (e.g. from `@revealui/utils/logger`).
+ */
+interface CacheLogger {
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+/**
+ * Replace the default console logger with a structured logger.
+ */
+declare function configureCacheLogger(logger: CacheLogger): void;
+/**
+ * Get the current cache logger instance.
+ */
+declare function getCacheLogger(): CacheLogger;
+
+export { type CDNCacheConfig, type CDNPurgeConfig, CDN_CACHE_PRESETS, type CacheLogger, DEFAULT_CDN_CONFIG, type EdgeCacheConfig, type EdgeRateLimitConfig, EdgeRateLimiter, type GeoLocation, type ISRConfig, ISR_PRESETS, type PersonalizationConfig, addPreloadLinks, configureCacheLogger, createCachedFunction, createEdgeCachedFetch, generateCacheControl, generateCacheTags, generateCloudflareConfig, generateStaticParams, generateVercelCacheConfig, getABTestVariant, getCacheLogger, getCacheTTL, getGeoLocation, getPersonalizationConfig, purgeAllCache, purgeCDNCache, purgeCacheByTag, revalidatePath, revalidatePaths, revalidateTag, revalidateTags, setEdgeCacheHeaders, shouldCacheResponse, warmCDNCache, warmISRCache };