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

package/src/types/index.ts

@@ -1,288 +0,0 @@
-import type { createLogger, LoggerOptions } from '@c15t/logger';
-import {
-	type Branding,
-	brandingValues,
-	type GlobalVendorList,
-	type NonIABVendor,
-} from '@c15t/schema/types';
-import type { Translations } from '@c15t/translations';
-import type { Meter, Tracer } from '@opentelemetry/api';
-import type { FumaDB, InferFumaDB } from 'fumadb';
-import type { CacheAdapter } from '../cache/types';
-import type { createRegistry } from '../db/registry';
-import type { DB, LatestDB } from '../db/schema';
-
-export * from './api';
-
-// Re-export from @c15t/schema for backward compatibility
-export const branding = brandingValues;
-export type { Branding };
-
-export interface DatabaseOptions {
-	/**
-	 * The database adapter to use.
-	 */
-	adapter: FumaDB<FumaDBSchema>['adapter'];
-
-	/**
-	 * Tenant ID for multi-tenant deployments.
-	 * When set, all database queries are automatically scoped to this tenant.
-	 */
-	tenantId?: string;
-
-	/**
-	 * Optional prefix for all database table names.
-	 * Useful when sharing a database with other applications to avoid naming conflicts.
-	 *
-	 * @example 'c15t_' // tables become: c15t_subject, c15t_consent, etc.
-	 */
-	tablePrefix?: string;
-}
-
-export interface AdvancedOptions {
-	/**
-	 * Disables the use of Geo Location to determine the jurisdiction
-	 *
-	 * When enabled, the jurisdiction will be set to "GDPR" to show the strictest version of the banner as we don't know the jurisdiction in this case
-	 *
-	 * @default false
-	 */
-	disableGeoLocation?: boolean;
-	/**
-	 * Override base translations
-	 *
-	 * @example
-	 * ```ts
-	 * {
-	 *   en: enTranslations,
-	 *   de: deTranslations,
-	 * }
-	 * ```
-	 */
-	customTranslations?: Record<string, Partial<Translations>>;
-
-	/**
-	 * Select which branding to show in the consent banner.
-	 * Use "none" to hide branding.
-	 * @default "c15t"
-	 */
-	branding?: Branding;
-
-	openapi?: {
-		/**
-		 * Enable/disable OpenAPI spec generation
-		 * @default true
-		 */
-		enabled?: boolean;
-
-		/**
-		 * Path to serve the OpenAPI JSON spec
-		 * @default "/spec.json"
-		 */
-		specPath?: string;
-
-		/**
-		 * Path to serve the API documentation UI
-		 * @default "/docs"
-		 */
-		docsPath?: string;
-
-		/**
-		 * OpenAPI specification options
-		 */
-		options?: {
-			info?: {
-				title?: string;
-				version?: string;
-				description?: string;
-			};
-			servers?: Array<{ url: string; description?: string }>;
-			security?: Array<Record<string, string[]>>;
-		};
-
-		/**
-		 * Custom template for rendering the API documentation UI
-		 * If provided, this will be used instead of the default Scalar UI
-		 */
-		customUiTemplate?: string;
-	};
-	/**
-	 * OpenTelemetry configuration for tracing and metrics.
-	 * Telemetry is opt-in and disabled by default.
-	 * Users must provide their own SDK setup (Node, Bun, edge, etc.).
-	 */
-	telemetry?: {
-		/**
-		 * Enable telemetry (tracing and metrics).
-		 * Must be explicitly set to true to activate.
-		 * @default false
-		 */
-		enabled?: boolean;
-		/**
-		 * User-provided tracer instance.
-		 * Users should set up their own OpenTelemetry SDK and pass the tracer here.
-		 * @example trace.getTracer('my-app')
-		 */
-		tracer?: Tracer;
-		/**
-		 * User-provided meter instance for metrics.
-		 * Users should set up their own OpenTelemetry SDK and pass the meter here.
-		 * @example metrics.getMeter('my-app')
-		 */
-		meter?: Meter;
-		/**
-		 * Default attributes to include on all spans and metrics.
-		 */
-		defaultAttributes?: Record<string, string | number | boolean>;
-	};
-	ipAddress?: {
-		/**
-		 * Enable/disable IP address tracking.
-		 * When disabled, all IP addresses will be stored as null.
-		 * @default true
-		 */
-		tracking?: boolean;
-
-		/**
-		 * Enable/disable IP address masking to reduce PII collection.
-		 * - IPv4: Last octet is replaced with 0 (e.g., 192.168.1.100 -> 192.168.1.0)
-		 * - IPv6: Last 80 bits are masked (e.g., 2001:db8:85a3::1 -> 2001:db8:85a3::)
-		 * @default true
-		 */
-		masking?: boolean;
-
-		/**
-		 * Override the default IP address headers used to extract client IP.
-		 * Headers are checked in order, first match wins.
-		 */
-		ipAddressHeaders?: string[];
-	};
-
-	/**
-	 * Cache configuration for external persistent storage.
-	 * Used for caching GVL and other data.
-	 */
-	cache?: {
-		/**
-		 * External cache adapter (Redis, KV, etc.).
-		 * If not provided, only in-memory cache is used.
-		 */
-		adapter?: CacheAdapter;
-	};
-
-	/**
-	 * API keys for authenticated endpoints.
-	 * Used for server-side endpoints like GET /subjects.
-	 *
-	 * @example
-	 * ```ts
-	 * apiKeys: ['sk_live_abc123', 'sk_live_def456']
-	 * ```
-	 */
-	apiKeys?: string[];
-
-	/**
-	 * GVL (Global Vendor List) configuration for IAB TCF compliance.
-	 * Disabled by default - most users don't need IAB TCF.
-	 * Set enabled: true to activate GVL support.
-	 */
-	gvl?: {
-		/**
-		 * Enable GVL support.
-		 * When false or not provided, /init returns gvl: null.
-		 */
-		enabled: true;
-
-		/**
-		 * Bundled GVL translations by language code.
-		 * These are checked first before any cache or fetch.
-		 *
-		 * @example
-		 * ```ts
-		 * import enGVL from './gvl/en.json';
-		 * import deGVL from './gvl/de.json';
-		 *
-		 * gvl: {
-		 *   enabled: true,
-		 *   bundled: { en: enGVL, de: deGVL }
-		 * }
-		 * ```
-		 */
-		bundled?: Record<string, GlobalVendorList>;
-
-		/**
-		 * Vendor IDs to filter when fetching non-bundled languages.
-		 * Reduces payload size.
-		 */
-		vendorIds?: number[];
-
-		/**
-		 * Override the default GVL endpoint.
-		 * @default 'https://gvl.consent.io'
-		 */
-		endpoint?: string;
-
-		/**
-		 * Custom vendors not registered with IAB.
-		 * These are synced to the frontend via the /init endpoint.
-		 *
-		 * @example
-		 * ```ts
-		 * customVendors: [
-		 *   {
-		 *     id: 'internal-analytics',
-		 *     name: 'Our Analytics',
-		 *     privacyPolicyUrl: 'https://example.com/privacy',
-		 *     purposes: [1, 8],
-		 *   }
-		 * ]
-		 * ```
-		 */
-		customVendors?: NonIABVendor[];
-	};
-}
-
-export interface BaseOptions {
-	/** Display name for your application, used in consent records. */
-	appName?: string;
-	/** Base path prefix for all API routes (e.g. `/api/consent`). */
-	basePath?: string;
-	/** Allowed origins for CORS. Required for browser-based consent collection. */
-	trustedOrigins: string[];
-	/** Advanced configuration options. */
-	advanced?: AdvancedOptions;
-}
-
-type FumaDBSchema = InferFumaDB<typeof DB>['schemas'];
-export interface C15TOptions extends BaseOptions, DatabaseOptions {
-	logger?: LoggerOptions;
-}
-
-export interface C15TContext extends BaseOptions {
-	appName: string;
-	logger: ReturnType<typeof createLogger>;
-	registry: ReturnType<typeof createRegistry>;
-	db: ReturnType<InferFumaDB<typeof LatestDB>['orm']>;
-
-	// Resolved from request
-	ipAddress?: string | null;
-	userAgent?: string;
-	origin?: string;
-	trustedOrigin?: boolean;
-	path?: string;
-	method?: string;
-	headers?: Headers;
-
-	// Authentication state
-	/**
-	 * Whether the request was authenticated with a valid API key.
-	 * Set to true when a valid Bearer token is provided in the Authorization header.
-	 */
-	apiKeyAuthenticated?: boolean;
-}
-
-export type DeepPartial<T> = T extends (...args: unknown[]) => unknown
-	? T
-	: T extends object
-		? { [K in keyof T]?: DeepPartial<T[K]> }
-		: T;

package/src/utils/create-telemetry-options.test.ts

@@ -1,302 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import type { C15TOptions } from '../types';
-import {
-	createRequestSpan,
-	createTelemetryOptions,
-	getDefaultAttributes,
-	getMeter,
-	getTraceContext,
-	getTracer,
-	isTelemetryEnabled,
-	resetTelemetryConfig,
-	withRequestSpan,
-} from './create-telemetry-options';
-
-afterEach(() => {
-	resetTelemetryConfig();
-});
-
-describe('createTelemetryOptions', () => {
-	it('returns disabled by default (opt-in)', () => {
-		const options = createTelemetryOptions('test-app');
-
-		expect(options?.enabled).toBe(false);
-	});
-
-	it('sets enabled when explicitly configured', () => {
-		const options = createTelemetryOptions('test-app', { enabled: true });
-
-		expect(options?.enabled).toBe(true);
-	});
-
-	it('includes default attributes with service name and version', () => {
-		const options = createTelemetryOptions('my-app');
-
-		expect(options?.defaultAttributes).toMatchObject({
-			'service.name': 'my-app',
-		});
-		expect(options?.defaultAttributes?.['service.version']).toBeDefined();
-	});
-
-	it('merges user-provided default attributes', () => {
-		const options = createTelemetryOptions('my-app', {
-			defaultAttributes: {
-				environment: 'production',
-				region: 'us-east-1',
-			},
-		});
-
-		expect(options?.defaultAttributes).toMatchObject({
-			'service.name': 'my-app',
-			environment: 'production',
-			region: 'us-east-1',
-		});
-	});
-
-	it('preserves user-provided tracer', () => {
-		const mockTracer = { startSpan: vi.fn() };
-		type TelemetryConfig = NonNullable<
-			NonNullable<C15TOptions['advanced']>['telemetry']
-		>;
-		const options = createTelemetryOptions('my-app', {
-			tracer: mockTracer as unknown as TelemetryConfig['tracer'],
-		});
-
-		expect(options?.tracer).toBe(mockTracer);
-	});
-});
-
-describe('isTelemetryEnabled', () => {
-	it('returns false when no options provided', () => {
-		expect(isTelemetryEnabled()).toBe(false);
-	});
-
-	it('returns false when telemetry is not configured', () => {
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-		};
-
-		expect(isTelemetryEnabled(options)).toBe(false);
-	});
-
-	it('returns false when enabled is not set', () => {
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-			advanced: {
-				telemetry: {},
-			},
-		};
-
-		expect(isTelemetryEnabled(options)).toBe(false);
-	});
-
-	it('returns true when enabled is true', () => {
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-			advanced: {
-				telemetry: {
-					enabled: true,
-				},
-			},
-		};
-
-		expect(isTelemetryEnabled(options)).toBe(true);
-	});
-});
-
-describe('getTracer', () => {
-	it('returns a tracer even when telemetry is disabled', () => {
-		const tracer = getTracer();
-
-		expect(tracer).toBeDefined();
-		expect(tracer.startSpan).toBeDefined();
-	});
-
-	it('uses user-provided tracer when available', () => {
-		const mockTracer = { startSpan: vi.fn() };
-		type TelemetryConfig = NonNullable<
-			NonNullable<C15TOptions['advanced']>['telemetry']
-		>;
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-			advanced: {
-				telemetry: {
-					enabled: true,
-					tracer: mockTracer as unknown as TelemetryConfig['tracer'],
-				},
-			},
-		};
-
-		const tracer = getTracer(options);
-		expect(tracer).toBe(mockTracer);
-	});
-});
-
-describe('getMeter', () => {
-	it('returns a meter even when telemetry is disabled', () => {
-		const meter = getMeter();
-
-		expect(meter).toBeDefined();
-		expect(meter.createCounter).toBeDefined();
-	});
-
-	it('returns meter with expected interface when telemetry is enabled', () => {
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-			advanced: {
-				telemetry: {
-					enabled: true,
-				},
-			},
-		};
-
-		const meter = getMeter(options);
-		// Verify the meter has the expected interface
-		expect(meter.createCounter).toBeDefined();
-		expect(meter.createHistogram).toBeDefined();
-	});
-});
-
-describe('createRequestSpan', () => {
-	it('returns null when telemetry is disabled', () => {
-		const span = createRequestSpan('GET', '/test');
-
-		expect(span).toBeNull();
-	});
-
-	it('creates span when telemetry is enabled', () => {
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-			advanced: {
-				telemetry: {
-					enabled: true,
-				},
-			},
-		};
-
-		const span = createRequestSpan('GET', '/test', options);
-
-		expect(span).toBeDefined();
-		// Clean up
-		span?.end();
-	});
-});
-
-describe('withRequestSpan', () => {
-	it('executes operation without span when telemetry is disabled', async () => {
-		const operation = vi.fn().mockResolvedValue('result');
-
-		const result = await withRequestSpan('GET', '/test', operation);
-
-		expect(result).toBe('result');
-		expect(operation).toHaveBeenCalledTimes(1);
-	});
-
-	it('wraps operation in span when telemetry is enabled', async () => {
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-			advanced: {
-				telemetry: {
-					enabled: true,
-				},
-			},
-		};
-		const operation = vi.fn().mockResolvedValue('result');
-
-		const result = await withRequestSpan('GET', '/test', operation, options);
-
-		expect(result).toBe('result');
-		expect(operation).toHaveBeenCalledTimes(1);
-	});
-
-	it('propagates errors from operation', async () => {
-		const error = new Error('Test error');
-		const operation = vi.fn().mockRejectedValue(error);
-
-		await expect(withRequestSpan('GET', '/test', operation)).rejects.toThrow(
-			'Test error'
-		);
-	});
-});
-
-describe('getTraceContext', () => {
-	it('returns null when no active span', () => {
-		const context = getTraceContext();
-
-		expect(context).toBeNull();
-	});
-});
-
-describe('cached telemetry config', () => {
-	it('isTelemetryEnabled returns false before init', () => {
-		expect(isTelemetryEnabled()).toBe(false);
-	});
-
-	it('isTelemetryEnabled returns cached value after init', () => {
-		createTelemetryOptions('test-app', { enabled: true });
-
-		expect(isTelemetryEnabled()).toBe(true);
-	});
-
-	it('getDefaultAttributes returns empty before init', () => {
-		const attrs = getDefaultAttributes();
-
-		expect(Object.keys(attrs)).toHaveLength(0);
-	});
-
-	it('getDefaultAttributes returns cached attributes after init', () => {
-		createTelemetryOptions('test-app', {
-			defaultAttributes: { environment: 'test' },
-		});
-
-		const attrs = getDefaultAttributes();
-		expect(attrs['service.name']).toBe('test-app');
-		expect(attrs['environment']).toBe('test');
-	});
-
-	it('includes tenantId in default attributes when provided', () => {
-		createTelemetryOptions('test-app', {}, 'tenant-123');
-
-		const attrs = getDefaultAttributes();
-		expect(attrs['tenant.id']).toBe('tenant-123');
-	});
-
-	it('does not include tenant.id when tenantId is undefined', () => {
-		createTelemetryOptions('test-app');
-
-		const attrs = getDefaultAttributes();
-		expect(attrs['tenant.id']).toBeUndefined();
-	});
-
-	it('resetTelemetryConfig clears the cache', () => {
-		createTelemetryOptions('test-app', { enabled: true });
-		expect(isTelemetryEnabled()).toBe(true);
-
-		resetTelemetryConfig();
-		expect(isTelemetryEnabled()).toBe(false);
-		expect(Object.keys(getDefaultAttributes())).toHaveLength(0);
-	});
-
-	it('getTracer returns a tracer without explicit options after init', () => {
-		createTelemetryOptions('test-app', { enabled: true });
-
-		const tracer = getTracer();
-		expect(tracer).toBeDefined();
-		expect(tracer.startSpan).toBeDefined();
-	});
-
-	it('getMeter returns a meter without explicit options after init', () => {
-		createTelemetryOptions('test-app', { enabled: true });
-
-		const meter = getMeter();
-		expect(meter).toBeDefined();
-		expect(meter.createCounter).toBeDefined();
-	});
-});