@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/types/index.ts

@@ -1,23 +1,288 @@
-/**
- * c15t Types Package
- *
- * This package provides type definitions specific to the c15t consent management system.
- * It extends the base DoubleTie framework types with consent management specific functionality.
- *
- * The types in this folder should be used for consent management specific features, while
- * more generic SDK functionality should remain in the DoubleTie base types.
- */
-
-// Export API specific types
-export type {
-	ApiPath,
-	ApiPathBase,
-} from './api';
-export type { C15TContext } from './context';
-// Re-export extended types that override doubletie base types
-export type { C15TOptions } from './options';
-// Export consent management specific types
-export type { C15TPlugin, InferPluginContexts } from './plugins';
-
-export const branding = ['c15t', 'consent', 'none'] as const;
-export type Branding = (typeof branding)[number];
+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

@@ -0,0 +1,302 @@
+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();
+	});
+});