@c15t/backend 2.0.0-rc.4 → 2.0.0-rc.6

package/src/types/index.ts

@@ -1,391 +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.
-	 *
-	 * @see {@link https://v2.c15t.com/docs/self-host/guides/database-setup}
-	 */
-	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.
-	 * @see {@link https://v2.c15t.com/docs/self-host/guides/database-setup}
-	 */
-	tablePrefix?: string;
-}
-
-/**
- * OpenAPI spec generation and documentation UI options.
- */
-export interface OpenAPIOptions {
-	/**
-	 * 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.).
- */
-export interface TelemetryOptions {
-	/**
-	 * 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>;
-}
-
-/**
- * IP address tracking and masking options.
- */
-export interface IPAddressOptions {
-	/**
-	 * 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.
- */
-export interface CacheOptions {
-	/**
-	 * External cache adapter (Redis, KV, etc.).
-	 * If not provided, only in-memory cache is used.
-	 */
-	adapter?: CacheAdapter;
-}
-
-/**
- * IAB TCF configuration including GVL, CMP registration, and custom vendors.
- * Disabled by default - most users don't need IAB TCF.
- * Set enabled: true to activate IAB support.
- */
-export interface IABOptions {
-	/**
-	 * Enable IAB TCF support.
-	 * When false or not provided, /init returns gvl: null.
-	 */
-	enabled: true;
-
-	/**
-	 * CMP ID registered with IAB Europe.
-	 * This is returned to clients via the /init endpoint so they
-	 * can use the correct CMP identity in TC Strings.
-	 *
-	 * @see https://iabeurope.eu/cmp-list/ - List of registered CMPs
-	 */
-	cmpId?: number;
-
-	/**
-	 * 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';
-	 *
-	 * iab: {
-	 *   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[];
-}
-
-type FumaDBSchema = InferFumaDB<typeof DB>['schemas'];
-
-export interface C15TOptions {
-	/**
-	 * The database adapter to use.
-	 *
-	 * @see {@link https://v2.c15t.com/docs/self-host/guides/database-setup}
-	 */
-	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.
-	 * @see {@link https://v2.c15t.com/docs/self-host/guides/database-setup}
-	 */
-	tablePrefix?: string;
-
-	/**
-	 * Application name used as backend metadata and identity.
-	 * Returned by `/init` (`appName`), used in logs, telemetry defaults (`service.name`),
-	 * and cache key prefixing.
-	 *
-	 * @default "c15t"
-	 * @see {@link https://v2.c15t.com/docs/self-host/api/configuration}
-	 */
-	appName?: string;
-
-	/**
-	 * Base path prefix for all API routes (e.g. `/api/self-host`).
-	 *
-	 * @see {@link https://v2.c15t.com/docs/self-host/api/endpoints}
-	 */
-	basePath?: string;
-
-	/**
-	 * Allowed origins for CORS. Required for browser-based consent collection.
-	 * Protocol is optional; matching is protocol-agnostic and normalized.
-	 *
-	 * @example ['example.com', 'app.example.com', 'localhost:3000']
-	 * @see {@link https://v2.c15t.com/docs/self-host/api/configuration}
-	 */
-	trustedOrigins: string[];
-
-	/** Logger configuration. */
-	logger?: LoggerOptions;
-
-	/**
-	 * 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 spec generation and documentation UI options.
-	 *
-	 * @see {@link https://v2.c15t.com/docs/self-host/api/endpoints}
-	 */
-	openapi?: OpenAPIOptions;
-
-	/**
-	 * 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.).
-	 *
-	 * @see {@link https://v2.c15t.com/docs/self-host/guides/observability}
-	 */
-	telemetry?: TelemetryOptions;
-
-	/**
-	 * IP address tracking and masking options.
-	 *
-	 * @see {@link https://v2.c15t.com/docs/self-host/api/configuration}
-	 */
-	ipAddress?: IPAddressOptions;
-
-	/**
-	 * Cache configuration for external persistent storage.
-	 * Used for caching GVL and other data.
-	 *
-	 * @see {@link https://v2.c15t.com/docs/self-host/guides/caching}
-	 */
-	cache?: CacheOptions;
-
-	/**
-	 * API keys for authenticated endpoints.
-	 * Used for server-side endpoints like GET /subjects.
-	 *
-	 * @example
-	 * ```ts
-	 * apiKeys: ['sk_live_abc123', 'sk_live_def456']
-	 * ```
-	 */
-	apiKeys?: string[];
-
-	/**
-	 * IAB TCF configuration including GVL, CMP registration, and custom vendors.
-	 * Disabled by default - most users don't need IAB TCF.
-	 * Set enabled: true to activate IAB support.
-	 *
-	 * @see {@link https://v2.c15t.com/docs/self-host/guides/iab-tcf}
-	 */
-	iab?: IABOptions;
-}
-
-export interface C15TContext
-	extends Omit<
-		C15TOptions,
-		'ipAddress' | 'adapter' | 'logger' | 'tablePrefix' | 'tenantId'
-	> {
-	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,286 +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<C15TOptions['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'],
-			telemetry: {},
-		};
-
-		expect(isTelemetryEnabled(options)).toBe(false);
-	});
-
-	it('returns true when enabled is true', () => {
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-			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<C15TOptions['telemetry']>;
-		const options: C15TOptions = {
-			trustedOrigins: [],
-			adapter: {} as C15TOptions['adapter'],
-			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'],
-			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'],
-			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'],
-			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();
-	});
-});