@c15t/backend 2.0.0-rc.3 → 2.0.0-rc.5

package/src/cache/adapters/memory.ts

@@ -1,111 +0,0 @@
-/**
- * In-Memory Cache Adapter
- *
- * A simple Map-based cache adapter with TTL support.
- * Used as the default first layer in the cache resolution chain.
- *
- * @packageDocumentation
- */
-
-import type { CacheAdapter } from '../types';
-import { MEMORY_TTL_MS } from '../types';
-
-interface CacheEntry<T = unknown> {
-	value: T;
-	expiresAt: number;
-}
-
-/**
- * Module-level cache shared across requests in the same worker/process.
- * This provides fast 0ms access for repeated requests.
- */
-const memoryCache = new Map<string, CacheEntry>();
-
-/**
- * Creates an in-memory cache adapter.
- *
- * Features:
- * - Uses a shared Map for fast access
- * - Supports TTL with lazy expiration
- * - Always used as the first cache layer by default
- *
- * @returns A CacheAdapter implementation backed by in-memory Map
- *
- * @example
- * ```typescript
- * const memoryAdapter = createMemoryCacheAdapter();
- *
- * await memoryAdapter.set('key', { data: 'value' }, 60000); // 1 minute TTL
- * const value = await memoryAdapter.get('key');
- * ```
- *
- * @public
- */
-export function createMemoryCacheAdapter(): CacheAdapter {
-	return {
-		async get<T>(key: string): Promise<T | null> {
-			const entry = memoryCache.get(key);
-
-			if (!entry) {
-				return null;
-			}
-
-			// Check if entry has expired (lazy expiration)
-			if (Date.now() > entry.expiresAt) {
-				memoryCache.delete(key);
-				return null;
-			}
-
-			return entry.value as T;
-		},
-
-		async set<T>(key: string, value: T, ttlMs = MEMORY_TTL_MS): Promise<void> {
-			memoryCache.set(key, {
-				value,
-				expiresAt: Date.now() + ttlMs,
-			});
-		},
-
-		async delete(key: string): Promise<void> {
-			memoryCache.delete(key);
-		},
-
-		async has(key: string): Promise<boolean> {
-			const entry = memoryCache.get(key);
-
-			if (!entry) {
-				return false;
-			}
-
-			// Check if entry has expired
-			if (Date.now() > entry.expiresAt) {
-				memoryCache.delete(key);
-				return false;
-			}
-
-			return true;
-		},
-	};
-}
-
-/**
- * Clears the entire in-memory cache.
- * Primarily used for testing.
- *
- * @public
- */
-export function clearMemoryCache(): void {
-	memoryCache.clear();
-}
-
-/**
- * Gets the current size of the in-memory cache.
- * Primarily used for debugging and monitoring.
- *
- * @returns The number of entries in the cache (may include expired entries)
- *
- * @public
- */
-export function getMemoryCacheSize(): number {
-	return memoryCache.size;
-}

package/src/cache/adapters/upstash-redis.ts

@@ -1,113 +0,0 @@
-/**
- * Upstash Redis Cache Adapter
- *
- * Cache adapter for Upstash Redis, suitable for serverless environments.
- *
- * Requires @upstash/redis to be installed as a peer dependency.
- *
- * @packageDocumentation
- */
-
-import { Redis } from '@upstash/redis';
-import type { CacheAdapter } from '../types';
-import { GVL_TTL_MS } from '../types';
-
-/**
- * Options for creating an Upstash Redis adapter.
- *
- * @public
- */
-export interface UpstashRedisAdapterOptions {
-	/**
-	 * Upstash Redis REST URL.
-	 */
-	url: string;
-
-	/**
-	 * Upstash Redis REST token.
-	 */
-	token: string;
-}
-
-/**
- * Creates an Upstash Redis cache adapter.
- *
- * **Note:** Requires `@upstash/redis` to be installed as a peer dependency.
- *
- * @param options - Upstash Redis connection options
- * @returns A CacheAdapter backed by Upstash Redis
- *
- * @example
- * ```typescript
- * import { createUpstashRedisAdapter } from '@c15t/backend/cache';
- *
- * const redisAdapter = createUpstashRedisAdapter({
- *   url: process.env.UPSTASH_REDIS_REST_URL,
- *   token: process.env.UPSTASH_REDIS_REST_TOKEN,
- * });
- *
- * await redisAdapter.set('key', { data: 'value' }, 3600000); // 1 hour TTL
- * const value = await redisAdapter.get('key');
- * ```
- *
- * @public
- */
-export function createUpstashRedisAdapter(
-	options: UpstashRedisAdapterOptions
-): CacheAdapter {
-	const client = new Redis({
-		url: options.url,
-		token: options.token,
-	});
-
-	return createUpstashRedisAdapterFromClient(client);
-}
-
-/**
- * Creates an Upstash Redis cache adapter from an existing client.
- *
- * Use this if you already have an @upstash/redis client instance.
- *
- * @param client - An existing Upstash Redis client
- * @returns A CacheAdapter backed by the provided client
- *
- * @example
- * ```typescript
- * import { Redis } from '@upstash/redis';
- * import { createUpstashRedisAdapterFromClient } from '@c15t/backend/cache';
- *
- * const redis = new Redis({
- *   url: process.env.UPSTASH_REDIS_REST_URL,
- *   token: process.env.UPSTASH_REDIS_REST_TOKEN,
- * });
- *
- * const adapter = createUpstashRedisAdapterFromClient(redis);
- * ```
- *
- * @public
- */
-export function createUpstashRedisAdapterFromClient(
-	client: Redis
-): CacheAdapter {
-	return {
-		async get<T>(key: string): Promise<T | null> {
-			const result = await client.get<T>(key);
-			return result ?? null;
-		},
-
-		async set<T>(key: string, value: T, ttlMs = GVL_TTL_MS): Promise<void> {
-			// Convert milliseconds to seconds for Redis EX
-			const ttlSeconds = Math.ceil(ttlMs / 1000);
-			await client.set(key, value, { ex: ttlSeconds });
-		},
-
-		async delete(key: string): Promise<void> {
-			await client.del(key);
-		},
-
-		async has(key: string): Promise<boolean> {
-			const exists = await client.exists(key);
-			return exists > 0;
-		},
-	};
-}

package/src/cache/gvl-resolver.ts

@@ -1,289 +0,0 @@
-/**
- * GVL Resolution Service
- *
- * Resolves Global Vendor List with multi-layer caching:
- * 1. Bundled translations (checked first)
- * 2. In-memory cache
- * 3. External cache (Redis/KV)
- * 4. Fetch from gvl.consent.io
- *
- * @packageDocumentation
- */
-
-import type { GlobalVendorList } from '@c15t/schema/types';
-import { withCacheSpan, withExternalSpan } from '~/utils/instrumentation';
-import { getMetrics } from '~/utils/metrics';
-import { createMemoryCacheAdapter } from './adapters/memory';
-import { createGVLCacheKey } from './keys';
-import type { CacheAdapter } from './types';
-import { GVL_TTL_MS, MEMORY_TTL_MS } from './types';
-
-/**
- * Default GVL endpoint.
- */
-const GVL_ENDPOINT = 'https://gvl.consent.io';
-
-/**
- * Options for creating a GVL resolver.
- *
- * @public
- */
-export interface GVLResolverOptions {
-	/**
-	 * The application name for cache key prefixing.
-	 */
-	appName: string;
-
-	/**
-	 * Bundled GVL translations by language code.
-	 * These are checked first before any cache.
-	 */
-	bundled?: Record<string, GlobalVendorList>;
-
-	/**
-	 * External cache adapter (Redis, KV, etc.).
-	 * If not provided, only in-memory cache is used.
-	 */
-	cacheAdapter?: CacheAdapter;
-
-	/**
-	 * Vendor IDs to filter when fetching from the GVL endpoint.
-	 * Reduces payload size.
-	 */
-	vendorIds?: number[];
-
-	/**
-	 * Override the default GVL endpoint.
-	 * @default 'https://gvl.consent.io'
-	 */
-	endpoint?: string;
-}
-
-/**
- * GVL resolver interface.
- *
- * @public
- */
-export interface GVLResolver {
-	/**
-	 * Get a localized GVL for the specified language.
-	 *
-	 * @param language - Language code (e.g., "en", "de")
-	 * @returns The GVL for the language, or null if unavailable
-	 */
-	get(language: string): Promise<GlobalVendorList | null>;
-}
-
-/**
- * In-flight request promises for deduplication.
- */
-const inflightRequests = new Map<string, Promise<GlobalVendorList | null>>();
-
-/**
- * Fetches GVL from the endpoint with the specified language.
- *
- * @param language - Language code for Accept-Language header
- * @param vendorIds - Optional vendor IDs to filter
- * @param endpoint - GVL endpoint URL
- * @returns The GVL or null if 204 (non-IAB region)
- */
-async function fetchGVLWithLanguage(
-	language: string,
-	vendorIds?: number[],
-	endpoint: string = GVL_ENDPOINT
-): Promise<GlobalVendorList | null> {
-	// Create a stable key for deduplication
-	const sortedVendorIds = vendorIds ? [...vendorIds].sort((a, b) => a - b) : [];
-	const dedupeKey = `${endpoint}|${language}|${sortedVendorIds.join(',')}`;
-
-	// Return in-flight request if one exists
-	const existingRequest = inflightRequests.get(dedupeKey);
-	if (existingRequest) {
-		return existingRequest;
-	}
-
-	// Build URL with vendor IDs filter
-	const url = new URL(endpoint);
-	if (sortedVendorIds.length > 0) {
-		url.searchParams.set('vendorIds', sortedVendorIds.join(','));
-	}
-
-	// Create and store the in-flight promise
-	const promise = (async () => {
-		const fetchStart = Date.now();
-		try {
-			const gvl = await withExternalSpan(
-				{ url: url.toString(), method: 'GET' },
-				async () => {
-					const response = await fetch(url.toString(), {
-						headers: {
-							'Accept-Language': language,
-						},
-					});
-
-					// 204 means non-IAB region - no GVL needed
-					if (response.status === 204) {
-						return null;
-					}
-
-					if (!response.ok) {
-						throw new Error(
-							`Failed to fetch GVL: ${response.status} ${response.statusText}`
-						);
-					}
-
-					// Use text() then JSON.parse to handle malformed responses (e.g. trailing
-					// content or BOM) that would break response.json()
-					const text = await response.text();
-					const trimmed = text.trim().replace(/^\uFEFF/, ''); // Strip BOM
-					let parsed: GlobalVendorList;
-					try {
-						parsed = JSON.parse(trimmed) as GlobalVendorList;
-					} catch {
-						// If response has valid JSON followed by extra content, try parsing
-						// only the first complete JSON value (find matching braces)
-						let depth = 0;
-						let end = -1;
-						const start = trimmed.indexOf('{');
-						if (start >= 0) {
-							for (let i = start; i < trimmed.length; i++) {
-								const c = trimmed[i];
-								if (c === '{') depth++;
-								else if (c === '}') {
-									depth--;
-									if (depth === 0) {
-										end = i + 1;
-										break;
-									}
-								}
-							}
-						}
-						if (end > 0) {
-							parsed = JSON.parse(trimmed.slice(0, end)) as GlobalVendorList;
-						} else {
-							throw new SyntaxError('Invalid GVL response: not valid JSON');
-						}
-					}
-
-					// Validate the response has required fields
-					if (
-						!parsed.vendorListVersion ||
-						!parsed.purposes ||
-						!parsed.vendors
-					) {
-						throw new Error('Invalid GVL response: missing required fields');
-					}
-
-					return parsed;
-				}
-			);
-
-			getMetrics()?.recordGvlFetch(
-				{ language, source: 'fetch', status: 200 },
-				Date.now() - fetchStart
-			);
-
-			return gvl;
-		} catch (error) {
-			getMetrics()?.recordGvlError({
-				language,
-				errorType: error instanceof Error ? error.name : 'UnknownError',
-			});
-			throw error;
-		} finally {
-			// Clear in-flight request when done
-			inflightRequests.delete(dedupeKey);
-		}
-	})();
-
-	inflightRequests.set(dedupeKey, promise);
-
-	return promise;
-}
-
-/**
- * Creates a GVL resolver with multi-layer caching.
- *
- * Resolution order:
- * 1. **Bundled** - Check bundled translations (0ms)
- * 2. **In-Memory** - Check worker/process memory cache (0ms)
- * 3. **External Cache** - Check Redis/KV if configured (20-40ms)
- * 4. **Fetch** - Fetch from gvl.consent.io with Accept-Language (100-300ms)
- *
- * @param options - Resolver configuration
- * @returns A GVL resolver instance
- *
- * @example
- * ```typescript
- * const resolver = createGVLResolver({
- *   appName: 'my-app',
- *   bundled: { en: enGVL },
- *   cacheAdapter: redisAdapter,
- *   vendorIds: [1, 2, 10],
- * });
- *
- * const gvl = await resolver.get('de');
- * ```
- *
- * @public
- */
-export function createGVLResolver(options: GVLResolverOptions): GVLResolver {
-	const { appName, bundled, cacheAdapter, vendorIds, endpoint } = options;
-
-	// Create the in-memory cache adapter (always used as first layer)
-	const memoryCache = createMemoryCacheAdapter();
-
-	return {
-		async get(language: string): Promise<GlobalVendorList | null> {
-			const cacheKey = createGVLCacheKey(appName, language, vendorIds);
-
-			// 1. Check bundled languages first (0ms)
-			if (bundled?.[language]) {
-				return bundled[language];
-			}
-
-			// 2. Check in-memory cache (0ms)
-			const memoryHit = await withCacheSpan('get', 'memory', () =>
-				memoryCache.get<GlobalVendorList>(cacheKey)
-			);
-			if (memoryHit) {
-				getMetrics()?.recordCacheHit('memory');
-				return memoryHit;
-			}
-			getMetrics()?.recordCacheMiss('memory');
-
-			// 3. Check external cache if configured (20-40ms)
-			if (cacheAdapter) {
-				const externalHit = await withCacheSpan('get', 'external', () =>
-					cacheAdapter.get<GlobalVendorList>(cacheKey)
-				);
-				if (externalHit) {
-					getMetrics()?.recordCacheHit('external');
-					// Populate memory cache for next request
-					await withCacheSpan('set', 'memory', () =>
-						memoryCache.set(cacheKey, externalHit, MEMORY_TTL_MS)
-					);
-					return externalHit;
-				}
-				getMetrics()?.recordCacheMiss('external');
-			}
-
-			// 4. Fetch from gvl.consent.io with Accept-Language header (100-300ms)
-			const gvl = await fetchGVLWithLanguage(language, vendorIds, endpoint);
-
-			if (gvl) {
-				// Populate both caches
-				await withCacheSpan('set', 'memory', () =>
-					memoryCache.set(cacheKey, gvl, MEMORY_TTL_MS)
-				);
-				if (cacheAdapter) {
-					await withCacheSpan('set', 'external', () =>
-						cacheAdapter.set(cacheKey, gvl, GVL_TTL_MS)
-					);
-				}
-			}
-
-			return gvl;
-		},
-	};
-}

package/src/cache/index.ts

@@ -1,34 +0,0 @@
-/**
- * Cache Module
- *
- * Multi-layer caching system with pluggable adapters for GVL and other data.
- *
- * @packageDocumentation
- */
-
-// Adapters
-export {
-	clearMemoryCache,
-	// Cloudflare KV
-	createCloudflareKVAdapter,
-	// Memory
-	createMemoryCacheAdapter,
-	// Upstash Redis
-	createUpstashRedisAdapter,
-	createUpstashRedisAdapterFromClient,
-	getMemoryCacheSize,
-	type KVNamespace,
-	type UpstashRedisAdapterOptions,
-} from './adapters';
-// GVL Resolver
-export {
-	createGVLResolver,
-	type GVLResolver,
-	type GVLResolverOptions,
-} from './gvl-resolver';
-
-// Cache Key Utilities
-export { createCacheKey, createGVLCacheKey } from './keys';
-// Types
-export type { CacheAdapter } from './types';
-export { GVL_TTL_MS, MEMORY_TTL_MS } from './types';

package/src/cache/keys.ts

@@ -1,68 +0,0 @@
-/**
- * Cache Key Utilities
- *
- * Functions for generating consistent cache keys with app name prefixing.
- *
- * @packageDocumentation
- */
-
-/**
- * Create a GVL cache key.
- *
- * Format: `{appName}:gvl:{language}:{sortedVendorIds}`
- *
- * @param appName - The application name for key prefixing
- * @param language - The language code (e.g., "en", "de")
- * @param vendorIds - Optional array of vendor IDs to include in the key
- * @returns A unique cache key for the GVL configuration
- *
- * @example
- * ```typescript
- * // All vendors
- * createGVLCacheKey('my-app', 'en');
- * // => 'my-app:gvl:en:all'
- *
- * // Specific vendors
- * createGVLCacheKey('my-app', 'de', [1, 10, 2]);
- * // => 'my-app:gvl:de:1,2,10'
- * ```
- *
- * @public
- */
-export function createGVLCacheKey(
-	appName: string,
-	language: string,
-	vendorIds?: number[]
-): string {
-	const sortedIds = vendorIds
-		? [...vendorIds].sort((a, b) => a - b).join(',')
-		: 'all';
-	return `${appName}:gvl:${language}:${sortedIds}`;
-}
-
-/**
- * Create a generic cache key with namespace and parts.
- *
- * Format: `{appName}:{namespace}:{part1}:{part2}:...`
- *
- * @param appName - The application name for key prefixing
- * @param namespace - The cache namespace (e.g., "gvl", "translations")
- * @param parts - Additional key parts
- * @returns A namespaced cache key
- *
- * @example
- * ```typescript
- * createCacheKey('my-app', 'translations', 'en', 'banner');
- * // => 'my-app:translations:en:banner'
- * ```
- *
- * @public
- */
-export function createCacheKey(
-	appName: string,
-	namespace: string,
-	...parts: (string | number)[]
-): string {
-	const allParts = [appName, namespace, ...parts];
-	return allParts.join(':');
-}

package/src/cache/types.ts

@@ -1,66 +0,0 @@
-/**
- * Cache Adapter Types
- *
- * Generic cache adapter interface for pluggable caching implementations.
- * Supports in-memory, Redis, Cloudflare KV, and custom adapters.
- *
- * @packageDocumentation
- */
-
-/**
- * Generic cache adapter interface.
- *
- * Implementations should handle serialization/deserialization internally.
- * All methods are async to support both sync (memory) and async (Redis/KV) backends.
- *
- * @public
- */
-export interface CacheAdapter {
-	/**
-	 * Get a value from the cache.
-	 *
-	 * @param key - Cache key
-	 * @returns The cached value, or null if not found or expired
-	 */
-	get<T>(key: string): Promise<T | null>;
-
-	/**
-	 * Set a value in the cache.
-	 *
-	 * @param key - Cache key
-	 * @param value - Value to cache
-	 * @param ttlMs - Time to live in milliseconds (optional)
-	 */
-	set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
-
-	/**
-	 * Delete a value from the cache.
-	 *
-	 * @param key - Cache key
-	 */
-	delete(key: string): Promise<void>;
-
-	/**
-	 * Check if a key exists in the cache.
-	 *
-	 * @param key - Cache key
-	 * @returns True if the key exists and is not expired
-	 */
-	has(key: string): Promise<boolean>;
-}
-
-/**
- * Default TTL for GVL cache entries (3 days).
- * Matches the typical GVL update frequency.
- *
- * @public
- */
-export const GVL_TTL_MS = 3 * 24 * 60 * 60 * 1000; // 3 days
-
-/**
- * Default TTL for in-memory cache entries (5 minutes).
- * Shorter TTL to handle worker restarts and keep memory usage low.
- *
- * @public
- */
-export const MEMORY_TTL_MS = 5 * 60 * 1000; // 5 minutes