@c15t/backend 0.0.1-rc.10

package/src/test/utils.ts

@@ -0,0 +1,244 @@
+import { vi } from 'vitest';
+import type { C15TContext } from '~/types';
+
+/**
+ * Creates a mock context for testing API endpoints
+ *
+ * @returns A mock C15TContext with default values
+ */
+export function createMockContext(): C15TContext {
+	return {
+		version: '1.0.0',
+		appName: 'test-app',
+		db: {
+			setConsent: vi.fn(),
+			getConsent: vi.fn(),
+			withdrawConsent: vi.fn(),
+			verifyConsent: vi.fn(),
+			getConsentHistory: vi.fn(),
+			getConsentPolicy: vi.fn(),
+			generateConsentReceipt: vi.fn(),
+		},
+		registry: {
+			findConsents: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					consents: [
+						{
+							id: 'test-consent-id',
+							domainId: 'example.com',
+							status: 'active',
+							givenAt: new Date().toISOString(),
+							consentWithdrawals: [],
+							records: [],
+						},
+					],
+					auditLogs: [],
+					pagination: { total: 1, offset: 0, limit: 100 },
+				},
+			}),
+			findConsentWithdrawals: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					consentWithdrawals: [],
+					auditLogs: [],
+					pagination: { total: 0, offset: 0, limit: 100 },
+				},
+			}),
+			findPolicies: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					policies: [],
+					auditLogs: [],
+					pagination: { total: 0, offset: 0, limit: 100 },
+				},
+			}),
+			findDomains: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					domains: [],
+					auditLogs: [],
+					pagination: { total: 0, offset: 0, limit: 100 },
+				},
+			}),
+			//@ts-expect-error
+			findJurisdictions: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					jurisdictions: [],
+					auditLogs: [],
+					pagination: { total: 0, offset: 0, limit: 100 },
+				},
+			}),
+			createConsent: vi.fn(),
+			createConsentWithdrawal: vi.fn(),
+			createDomain: vi.fn(),
+			updateConsent: vi.fn(),
+			updateWithdrawal: vi.fn(),
+			updateDomain: vi.fn(),
+			getConsent: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					id: 'test-consent-id',
+					subjectId: 'test-subject',
+					domainId: 'example.com',
+					status: 'active',
+					givenAt: new Date().toISOString(),
+					preferences: {
+						marketing: 'granted',
+						analytics: 'granted',
+						preferences: 'granted',
+					},
+				},
+			}),
+			getWithdrawal: vi.fn(),
+			getPolicy: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					id: 'test-policy-id',
+					domain: 'example.com',
+					version: '1.0',
+					content: 'Test policy content',
+					availablePreferences: {
+						marketing: ['granted', 'denied'],
+						analytics: ['granted', 'denied'],
+						preferences: ['granted', 'denied'],
+					},
+					createdAt: new Date().toISOString(),
+				},
+			}),
+			getDomain: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					id: 'example.com',
+					name: 'Example Domain',
+					policyId: 'test-policy-id',
+					createdAt: new Date().toISOString(),
+				},
+			}),
+			getJurisdiction: vi.fn().mockResolvedValue({
+				success: true,
+				data: {
+					code: 'EU',
+					name: 'European Union',
+					requiresConsent: true,
+					createdAt: new Date().toISOString(),
+				},
+			}),
+		},
+		logger: {
+			info: vi.fn(),
+			error: vi.fn(),
+			warn: vi.fn(),
+			debug: vi.fn(),
+			success: vi.fn(),
+		},
+		options: {
+			plugins: [],
+			logger: {
+				level: 'info',
+				disabled: false,
+			},
+		},
+		baseURL: 'http://localhost:3000',
+		ipAddress: '127.0.0.1',
+	};
+}
+
+/**
+ * Creates a mock request for testing
+ *
+ * @param url - The request URL
+ * @param method - The HTTP method
+ * @param body - Optional request body
+ * @returns A mock Request object
+ */
+export function createMockRequest(
+	url: string,
+	method = 'GET',
+	body?: unknown
+): Request {
+	return new Request(url, {
+		method,
+		headers: {
+			'Content-Type': 'application/json',
+		},
+		body: body ? JSON.stringify(body) : undefined,
+	});
+}
+
+/**
+ * Creates a mock response for testing
+ *
+ * @param status - The HTTP status code
+ * @param body - The response body
+ * @returns A mock Response object
+ */
+export function createMockResponse(status: number, body: unknown): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: {
+			'Content-Type': 'application/json',
+		},
+	});
+}
+
+/**
+ * Helper to create a mock consent object
+ *
+ * @param overrides - Optional overrides for the default consent object
+ * @returns A mock consent object
+ */
+export function createMockConsent(
+	overrides: Partial<{
+		subjectId: string;
+		domain: string;
+		preferences: Record<string, string>;
+		status: string;
+		givenAt: string;
+	}> = {}
+) {
+	return {
+		subjectId: 'test-subject',
+		domain: 'example.com',
+		preferences: {
+			marketing: 'granted',
+			analytics: 'granted',
+			preferences: 'granted',
+		},
+		status: 'active',
+		givenAt: new Date().toISOString(),
+		...overrides,
+	};
+}
+
+/**
+ * Helper to create a mock consent policy
+ *
+ * @param overrides - Optional overrides for the default policy object
+ * @returns A mock consent policy object
+ */
+export function createMockPolicy(
+	overrides: Partial<{
+		id: string;
+		domain: string;
+		version: string;
+		content: string;
+		availablePreferences: Record<string, string[]>;
+		createdAt: string;
+	}> = {}
+) {
+	return {
+		id: 'test-policy-id',
+		domain: 'example.com',
+		version: '1.0',
+		content: 'Test policy content',
+		availablePreferences: {
+			marketing: ['granted', 'denied'],
+			analytics: ['granted', 'denied'],
+			preferences: ['granted', 'denied'],
+		},
+		createdAt: new Date().toISOString(),
+		...overrides,
+	};
+}

package/src/types/api.ts

@@ -0,0 +1,101 @@
+/**
+ * API Types for c15t
+ *
+ * Definitions for API routes, request handlers, and endpoint configuration
+ */
+import type { Endpoint } from 'better-call';
+
+/**
+ * Filter action methods from an object type
+ *
+ * This type utility extracts only the method properties from an object type,
+ * useful for API type inference.
+ *
+ * @typeParam TObject - The object type to filter action methods from
+ *
+ * @example
+ * ```ts
+ * interface APIHandlers {
+ *   getSubject: (id: string) => Promise<Subject>;
+ *   userData: Subject;
+ *   updateSubject: (subject: Subject) => Promise<void>;
+ * }
+ *
+ * // ActionKeys will be 'getSubject' | 'updateSubject'
+ * type ActionKeys = FilterActions<APIHandlers>[keyof FilterActions<APIHandlers>];
+ * ```
+ */
+export type FilterActions<TObject extends Record<string, unknown>> = {
+	[Key in keyof TObject]: TObject[Key] extends (...args: unknown[]) => unknown
+		? Key
+		: never;
+};
+
+/**
+ * Base API path template literal for c15t endpoints
+ *
+ * This type defines the base path for all API routes in the c15t system.
+ * Used as a foundation for building type-safe API route paths.
+ *
+ * @see ApiPath for complete path patterns
+ */
+export type ApiPathBase = `/api/c15t`;
+
+/**
+ * API route path with strict type checking
+ *
+ * This type union represents all valid API paths in the system.
+ * It enforces type safety when defining routes or middlewares to
+ * prevent typos and ensure consistency.
+ *
+ * @example
+ * ```ts
+ * // Valid API path
+ * const consentPath: ApiPath = '/api/c15t/consent';
+ *
+ * // Invalid - would cause a type error
+ * const invalidPath: ApiPath = '/api/c15t/unknown-endpoint';
+ * ```
+ */
+export type ApiPath =
+	| `${ApiPathBase}`
+	| `${ApiPathBase}/consent`
+	| `${ApiPathBase}/consent/:id`
+	| `${ApiPathBase}/jurisdictions`
+	| `${ApiPathBase}/jurisdictions/:code`
+	| `${ApiPathBase}/plugins/:id`;
+
+/**
+ * Strongly-typed middleware configuration
+ *
+ * Defines the structure for API middleware registrations,
+ * ensuring that both the path and middleware function are properly typed.
+ *
+ * @see ApiPath for valid path patterns
+ *
+ * @example
+ * ```ts
+ * // Register a middleware for the consent endpoint
+ * const authMiddleware: ApiMiddleware = {
+ *   path: '/api/c15t/consent',
+ *   middleware: async (ctx, next) => {
+ *     // Verify authentication
+ *     if (!ctx.request.headers.get('Authorization')) {
+ *       return ctx.json({ error: 'Unauthorized' }, { status: 401 });
+ *     }
+ *     return next();
+ *   }
+ * };
+ * ```
+ */
+export interface ApiMiddleware {
+	/**
+	 * The API path to apply this middleware to
+	 */
+	path: ApiPath;
+
+	/**
+	 * The middleware function to execute
+	 */
+	middleware: Endpoint;
+}

package/src/types/context.ts

@@ -0,0 +1,235 @@
+import type {
+	EndpointContext,
+	EndpointOptions,
+	InputContext,
+} from 'better-call';
+import type { getConsentTables } from '~/db';
+import type { Adapter } from '~/db/adapters/types';
+import type { EntityName } from '~/db/core/types';
+import type { createRegistry } from '~/db/create-registry';
+import type { DatabaseHook } from '~/db/hooks/types';
+import type { createLogger } from '~/utils';
+import type { C15TOptions } from './index';
+
+/**
+ * Extended endpoint context for hooks
+ *
+ * This type extends the standard endpoint context with additional properties
+ * specific to c15t hooks, allowing hooks to access the complete c15t context.
+ *
+ * @typeParam TOptions - Endpoint configuration options type
+ *
+ * @see GenericEndpointContext for a simpler context type without input context inclusion
+ */
+export type HookEndpointContext<
+	TOptions extends EndpointOptions = EndpointOptions,
+> = EndpointContext<string, TOptions> &
+	Omit<InputContext<string, TOptions>, 'method'> & {
+		/**
+		 * The c15t context with possible hook-specific extensions
+		 */
+		context: C15TContext & {
+			/**
+			 * Value returned by the endpoint handler, available in 'after' hooks
+			 */
+			returned?: unknown;
+
+			/**
+			 * Response headers, available in 'after' hooks
+			 */
+			responseHeaders?: Headers;
+		};
+
+		/**
+		 * Request headers
+		 */
+		headers?: Headers;
+	};
+
+/**
+ * Standard endpoint context for c15t handlers
+ *
+ * A simplified context type that includes the c15t context,
+ * used by endpoint handlers throughout the system.
+ *
+ * @typeParam TOptions - Endpoint configuration options type
+ */
+export type GenericEndpointContext<
+	TOptions extends EndpointOptions = EndpointOptions,
+> = EndpointContext<string, TOptions> & {
+	/**
+	 * The c15t application context
+	 */
+	context: C15TContext;
+};
+
+/**
+ * Base shared context for all c15t components
+ *
+ * Contains the minimal set of properties needed by all components
+ * in the c15t system, including configuration options and logging.
+ */
+export interface BaseContext {
+	/**
+	 * Configuration options for the c15t system
+	 */
+	options: C15TOptions;
+
+	/**
+	 * Logger instance for recording events and errors
+	 */
+	logger: ReturnType<typeof createLogger>;
+}
+
+/**
+ * Registry-specific context for database adapters
+ *
+ * Extends the base context with properties needed for
+ * database operations and entity management.
+ */
+export interface RegistryContext extends BaseContext {
+	/**
+	 * Database adapter instance
+	 */
+	adapter: Adapter;
+
+	/**
+	 * Database lifecycle hooks
+	 */
+	hooks: DatabaseHook[];
+
+	/**
+	 * Function to generate unique IDs for entities
+	 *
+	 * @param options - Options for ID generation including entity type and length
+	 * @returns A unique ID string
+	 */
+	generateId: (options: { model: EntityName; size?: number }) => string;
+}
+
+/**
+ * Base context without plugin-specific extensions
+ *
+ * This interface defines the core context properties available to all
+ * components in the c15t system before plugin extensions are applied.
+ */
+export interface BaseC15TContext {
+	/**
+	 * Application name displayed in consent dialogs
+	 */
+	appName: string;
+
+	/**
+	 * Configuration options for the c15t system
+	 */
+	options: C15TOptions;
+
+	/**
+	 * List of origins that are trusted for CORS and CSRF protection
+	 */
+	trustedOrigins: string[];
+
+	/**
+	 * Base URL for API requests
+	 */
+	baseURL: string;
+
+	/**
+	 * Secret key used for signing cookies and tokens
+	 */
+	secret: string;
+
+	/**
+	 * Logger instance for recording events and errors
+	 */
+	logger: ReturnType<typeof createLogger>;
+
+	/**
+	 * Function to generate unique IDs for entities
+	 *
+	 * @param options - Options for ID generation including entity type and length
+	 * @returns A unique ID string
+	 */
+	generateId: (options: { model: EntityName; size?: number }) => string;
+
+	/**
+	 * Database adapter instance
+	 */
+	adapter: Adapter;
+
+	/**
+	 * Entity registry for database operations
+	 */
+	registry: ReturnType<typeof createRegistry>;
+
+	/**
+	 * Database tables for the consent system
+	 */
+	tables: ReturnType<typeof getConsentTables>;
+
+	/**
+	 * IP address of the client
+	 */
+	ipAddress?: string | null;
+
+	/**
+	 * Subject agent of the client
+	 */
+	userAgent?: string | null;
+}
+
+/**
+ * Extended context type with plugin extensions
+ *
+ * This type extends the base context with plugin-specific properties,
+ * allowing plugins to add their own functionality to the context.
+ *
+ * @typeParam TPluginContext - Record of plugin-specific context extensions
+ *
+ * @example
+ * ```ts
+ * // Plugin extending the context with analytics capabilities
+ * interface AnalyticsContext {
+ *   analytics: {
+ *     trackEvent: (event: string, data: unknown) => void;
+ *     getSessionId: () => string;
+ *   }
+ * }
+ *
+ * // Using the extended context in a component
+ * function handleConsent(ctx: C15TContext<AnalyticsContext>) {
+ *   // Base context is available
+ *   const { baseURL, logger } = ctx;
+ *
+ *   // Plugin context is also available
+ *   ctx.analytics.trackEvent('consent_given', { timestamp: Date.now() });
+ * }
+ * ```
+ */
+export type C15TContext<
+	TPluginContext extends Record<string, unknown> = Record<string, unknown>,
+> = BaseC15TContext & TPluginContext;
+
+/**
+ * Helper to extract context with a specific plugin's context type
+ *
+ * This utility type makes it easier to work with context that has been
+ * extended by a specific plugin, providing proper type information.
+ *
+ * @typeParam TPluginName - The name of the plugin providing the context extension
+ * @typeParam TPluginContext - The type of the context extension provided by the plugin
+ *
+ * @example
+ * ```ts
+ * // Working with a specific plugin's context
+ * function useGeoPlugin(ctx: ContextWithPlugin<'geo', GeoPluginContext>) {
+ *   // TypeScript knows that ctx.geo exists and has the right type
+ *   const country = ctx.geo.getCurrentCountry();
+ *   return country;
+ * }
+ * ```
+ */
+export type ContextWithPlugin<
+	TPluginName extends string,
+	TPluginContext extends Record<string, unknown>,
+> = C15TContext<Record<TPluginName, TPluginContext>>;

package/src/types/helper.ts

@@ -0,0 +1,87 @@
+/**
+ * Represents a string literal type
+ *
+ * This type ensures that only string literals are accepted, not general string types.
+ * It's useful for ensuring type safety with specific string values.
+ *
+ * @example
+ * ```ts
+ * // Function that only accepts literal strings, not string variables
+ * function doSomething(value: LiteralString) {
+ *   // Implementation
+ * }
+ *
+ * // Valid usage:
+ * doSomething('specific-value');
+ *
+ * // Invalid usage:
+ * const dynamicString = getStringFromSomewhere();
+ * doSomething(dynamicString); // Type error
+ * ```
+ */
+export type LiteralString = '' | (string & Record<never, never>);
+
+/**
+ * Extracts all required keys from an object type
+ *
+ * This utility type identifies which keys in an object type are required
+ * (not optional or undefined). Useful for type manipulation in complex types.
+ *
+ * @typeParam BaseType - The object type to extract required keys from
+ *
+ * @example
+ * ```ts
+ * interface Subject {
+ *   id: number;
+ *   name: string;
+ *   email?: string;
+ * }
+ *
+ * // RequiredKeysOf<Subject> will be 'id' | 'name'
+ * type RequiredsubjectFields = RequiredKeysOf<Subject>;
+ * ```
+ */
+export type RequiredKeysOf<BaseType extends object> = Exclude<
+	{
+		[Key in keyof BaseType]: BaseType extends Record<Key, BaseType[Key]>
+			? Key
+			: never;
+	}[keyof BaseType],
+	undefined
+>;
+
+/**
+ * Makes all properties in an object type optional recursively
+ *
+ * Unlike TypeScript's built-in Partial<T>, this type makes nested object
+ * properties optional as well. Functions are preserved as-is.
+ *
+ * @typeParam T - The type to make deeply partial
+ */
+export type DeepPartial<T> = T extends (...args: unknown[]) => unknown
+	? T
+	: T extends object
+		? { [K in keyof T]?: DeepPartial<T[K]> }
+		: T;
+
+/**
+ * Recursively expands object types for better IntelliSense
+ *
+ * This utility improves type display in editors by expanding nested type
+ * definitions. Particularly useful when working with complex types
+ * created through composition or manipulation.
+ *
+ * @typeParam T - The type to expand recursively
+ *
+ * @example
+ * ```ts
+ * // Before expansion: Intersection of multiple types
+ * type ComplexType = TypeA & TypeB & { extraProp: string };
+ *
+ * // After expansion: Flat object type with all properties visible
+ * type ExpandedType = ExpandRecursively<ComplexType>;
+ * ```
+ */
+export type ExpandRecursively<T> = T extends infer O
+	? { [K in keyof O]: O[K] }
+	: never;

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export type * from './api';
+export type * from './context';
+export type * from './helper';
+export type * from './options';
+export type * from './plugins';