@c15t/backend 2.0.0-rc.0 → 2.0.0-rc.10

package/rslib.config.ts

@@ -1,93 +0,0 @@
-import { defineConfig } from '@rslib/core';
-import { getRsdoctorPlugins } from '../shared/rslib-utils';
-
-const externals = [
-	// Frameworks
-	'hono',
-	'express',
-	'next',
-
-	// UI frameworks
-	'react',
-	'vue',
-	'solid-js',
-	'solid-js/store',
-	'next/headers',
-	'$app/environment',
-	'@vue/runtime-dom',
-	'@vue/runtime-core',
-	'@vue/shared',
-	'@vue/reactivity',
-	'@vue/compiler-dom',
-	'@vue/compiler-core',
-	'csstype',
-
-	// Testing libraries
-	'vitest',
-	'@vitest/runner',
-	'@vitest/utils',
-	'@vitest/expect',
-	'@vitest/snapshot',
-	'@vitest/spy',
-	'chai',
-	'tinyspy',
-
-	// Utilities and others
-	'pathe',
-	'std-env',
-	'magic-string',
-	'pretty-format',
-	'p-limit',
-	'next/dist/compiled/@edge-runtime/cookies',
-	'@babel/types',
-	'@babel/parser',
-	'punycode',
-];
-
-export default defineConfig({
-	source: {
-		entry: {
-			core: ['./src/core.ts'],
-			router: ['./src/router.ts'],
-			'db/schema': ['./src/db/schema/index.ts'],
-			'db/adapters': ['./src/db/adapters/index.ts'],
-			'db/adapters/kysely': ['./src/db/adapters/kysely.ts'],
-			'db/adapters/drizzle': ['./src/db/adapters/drizzle.ts'],
-			'db/adapters/prisma': ['./src/db/adapters/prisma.ts'],
-			'db/adapters/typeorm': ['./src/db/adapters/typeorm.ts'],
-			'db/adapters/mongo': ['./src/db/adapters/mongo.ts'],
-			'db/migrator': ['./src/db/migrator/index.ts'],
-			'define-config': ['./src/define-config.ts'],
-			types: ['./src/types/index.ts'],
-			cache: ['./src/cache/index.ts'],
-		},
-	},
-	lib: [
-		{
-			dts: true,
-			bundle: true,
-			format: 'esm',
-			output: {
-				externals,
-			},
-		},
-		{
-			dts: true,
-			bundle: true,
-			format: 'cjs',
-			output: {
-				externals,
-			},
-		},
-	],
-	output: {
-		target: 'node',
-		cleanDistPath: true,
-		externals,
-	},
-	tools: {
-		rspack: {
-			plugins: [...getRsdoctorPlugins()],
-		},
-	},
-});

package/src/cache/adapters/cloudflare-kv.ts

@@ -1,71 +0,0 @@
-/**
- * Cloudflare KV Cache Adapter
- *
- * Cache adapter for Cloudflare Workers KV storage.
- *
- * @packageDocumentation
- */
-
-import type { CacheAdapter } from '../types';
-import { GVL_TTL_MS } from '../types';
-
-/**
- * Cloudflare KV Namespace interface.
- * Matches the KVNamespace type from @cloudflare/workers-types.
- *
- * @public
- */
-export interface KVNamespace {
-	get(key: string, options?: { type?: 'text' | 'json' }): Promise<unknown>;
-	put(
-		key: string,
-		value: string,
-		options?: { expirationTtl?: number }
-	): Promise<void>;
-	delete(key: string): Promise<void>;
-}
-
-/**
- * Creates a Cloudflare KV cache adapter.
- *
- * @param kv - Cloudflare KV namespace binding
- * @returns A CacheAdapter backed by Cloudflare KV
- *
- * @example
- * ```typescript
- * // In your Cloudflare Worker
- * export default {
- *   async fetch(request, env) {
- *     const kvAdapter = createCloudflareKVAdapter(env.GVL_CACHE);
- *
- *     await kvAdapter.set('key', { data: 'value' }, 3600000);
- *     const value = await kvAdapter.get('key');
- *   }
- * };
- * ```
- *
- * @public
- */
-export function createCloudflareKVAdapter(kv: KVNamespace): CacheAdapter {
-	return {
-		async get<T>(key: string): Promise<T | null> {
-			const value = await kv.get(key, { type: 'json' });
-			return value as T | null;
-		},
-
-		async set<T>(key: string, value: T, ttlMs = GVL_TTL_MS): Promise<void> {
-			// Convert milliseconds to seconds for KV expirationTtl
-			const ttlSeconds = Math.ceil(ttlMs / 1000);
-			await kv.put(key, JSON.stringify(value), { expirationTtl: ttlSeconds });
-		},
-
-		async delete(key: string): Promise<void> {
-			await kv.delete(key);
-		},
-
-		async has(key: string): Promise<boolean> {
-			const value = await kv.get(key);
-			return value !== null;
-		},
-	};
-}

package/src/cache/adapters/index.ts

@@ -1,22 +0,0 @@
-/**
- * Cache Adapters
- *
- * Pluggable cache adapter implementations for different storage backends.
- *
- * @packageDocumentation
- */
-
-export {
-	createCloudflareKVAdapter,
-	type KVNamespace,
-} from './cloudflare-kv';
-export {
-	clearMemoryCache,
-	createMemoryCacheAdapter,
-	getMemoryCacheSize,
-} from './memory';
-export {
-	createUpstashRedisAdapter,
-	createUpstashRedisAdapterFromClient,
-	type UpstashRedisAdapterOptions,
-} from './upstash-redis';

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;
-		},
-	};
-}