@c15t/backend 0.0.1-rc.10

package/src/api/routes/get-consent-policy.ts

@@ -0,0 +1,327 @@
+import { z } from 'zod';
+import type { EntityOutputFields } from '~/db/schema/definition';
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { C15TContext } from '../../types';
+import { createAuthEndpoint } from '../call';
+
+// Define the schema for the base parameters (domain is always required)
+const baseParamsSchema = z.object({
+	domain: z.string(),
+	version: z.string().optional(),
+	includePreferences: z.boolean().optional().default(true),
+});
+
+// Define schemas for the different identification methods (all optional)
+const subjectIdentifierSchema = z.object({
+	subjectId: z.string().optional(),
+	externalId: z.string().optional(),
+	ipAddress: z.string().optional(),
+});
+
+// Combine the schemas
+const getPolicySchema = baseParamsSchema.merge(subjectIdentifierSchema);
+
+export interface GetPolicyResponse {
+	success: boolean;
+	data: {
+		policy: {
+			id: string;
+			domain: string;
+			version: string;
+			content: string;
+			availablePreferences?: Record<string, unknown>;
+			createdAt: string;
+		};
+		subjectConsentStatus?: {
+			hasConsent: boolean;
+			currentPreferences: Record<string, string | null> | null;
+			consentedAt: string | null;
+			needsRenewal: boolean;
+			identifiedBy: string | null;
+		};
+	};
+}
+
+/**
+ * Endpoint for retrieving consent policy information.
+ *
+ * This endpoint allows clients to retrieve the consent policy for a domain.
+ * It supports retrieving the latest policy or a specific version.
+ * It can also return personalized policy information if subject identifiers are provided.
+ *
+ * @endpoint GET /consent/policy
+ * @requestExample
+ * ```
+ * // Basic policy request
+ * GET /api/consent/policy?domain=example.com
+ * ```
+ *
+ * @requestExample
+ * ```
+ * // Specific version
+ * GET /api/consent/policy?domain=example.com&version=1.2
+ * ```
+ *
+ * @requestExample
+ * ```
+ * // With subject context
+ * GET /api/consent/policy?domain=example.com&subjectId=550e8400-e29b-41d4-a716-446655440000
+ * ```
+ *
+ * @responseExample
+ * ```json
+ * {
+ *   "success": true,
+ *   "data": {
+ *     "policy": {
+ *       "id": 1,
+ *       "domain": "example.com",
+ *       "version": "1.0",
+ *       "content": {
+ *         "title": "Privacy Policy",
+ *         "description": "How we use your data",
+ *         "lastUpdated": "2023-04-01"
+ *       },
+ *       "availablePreferences": {
+ *         "marketing": {
+ *           "title": "Marketing",
+ *           "description": "Allow us to send you marketing communications",
+ *           "default": false
+ *         },
+ *         "analytics": {
+ *           "title": "Analytics",
+ *           "description": "Allow us to collect usage data to improve our service",
+ *           "default": true
+ *         }
+ *       },
+ *       "createdAt": "2023-04-01T12:34:56.789Z"
+ *     },
+ *     "subjectConsentStatus": {
+ *       "hasConsent": true,
+ *       "currentPreferences": {
+ *         "marketing": null,
+ *         "analytics": "2023-04-02T10:30:00.000Z"
+ *       },
+ *       "consentedAt": "2023-04-02T10:30:00.000Z",
+ *       "needsRenewal": false
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @returns {Object} Result of getting policy
+ * @returns {boolean} success - Whether the request was successful
+ * @returns {Object} data - The policy data
+ * @returns {Object} data.policy - The consent policy information
+ * @returns {Object} [data.subjectConsentStatus] - Subject's consent status if subject identifiers were provided
+ *
+ * @throws {C15TError} BAD_REQUEST - When request parameters are invalid
+ * @throws {C15TError} NOT_FOUND - When the domain or policy version doesn't exist
+ */
+export const getConsentPolicy = createAuthEndpoint(
+	'/consent/policy',
+	{
+		method: 'GET',
+		query: getPolicySchema,
+	},
+	async (ctx) => {
+		try {
+			const validatedData = getPolicySchema.safeParse(ctx.query);
+
+			if (!validatedData.success) {
+				throw new C15TError('BAD_REQUEST', {
+					code: BASE_ERROR_CODES.BAD_REQUEST,
+					status: 400,
+					data: {
+						message: 'Invalid request data',
+						details: validatedData.error.errors,
+					},
+				});
+			}
+
+			const params = validatedData.data;
+			const { registry } = ctx.context as C15TContext;
+
+			if (!registry) {
+				throw new C15TError('INTERNAL_SERVER_ERROR', {
+					code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+					status: 503,
+					data: {
+						message: 'Registry not available',
+					},
+				});
+			}
+
+			// Find domain
+			let domain: EntityOutputFields<'domain'> | null = null;
+			try {
+				if (registry.findDomain) {
+					domain = await registry.findDomain(params.domain);
+				}
+			} catch {
+				throw new C15TError(
+					'The specified domain could not be found. Please verify the domain name and try again.',
+					{
+						code: BASE_ERROR_CODES.NOT_FOUND,
+						status: 404,
+						data: {
+							domain: params.domain,
+						},
+					}
+				);
+			}
+
+			if (!domain) {
+				throw new C15TError(
+					'The specified domain could not be found. Please verify the domain name and try again.',
+					{
+						code: BASE_ERROR_CODES.NOT_FOUND,
+						status: 404,
+						data: {
+							domain: params.domain,
+						},
+					}
+				);
+			}
+
+			// Find the policy
+			let policy: EntityOutputFields<'consentPolicy'> | null = null;
+			try {
+				if (registry.findPolicy) {
+					policy = await registry.findPolicy(domain.id, params.version);
+				}
+			} catch {
+				throw new C15TError(
+					params.version
+						? `The specified policy version ${params.version} for domain ${params.domain} could not be found. Please verify the version number and domain name, and try again.`
+						: `No policy could be found for the domain ${params.domain}. Please ensure the domain name is correct and try again.`,
+					{
+						code: BASE_ERROR_CODES.NOT_FOUND,
+						status: 404,
+						data: {
+							domain: params.domain,
+							version: params.version,
+						},
+					}
+				);
+			}
+
+			if (!policy) {
+				throw new C15TError(
+					params.version
+						? `The specified policy version ${params.version} for domain ${params.domain} could not be found. Please verify the version number and domain name, and try again.`
+						: `No policy could be found for the domain ${params.domain}. Please ensure the domain name is correct and try again.`,
+					{
+						code: BASE_ERROR_CODES.NOT_FOUND,
+						status: 404,
+						data: {
+							domain: params.domain,
+							version: params.version,
+						},
+					}
+				);
+			}
+
+			// Format basic response
+			const response: GetPolicyResponse = {
+				success: true,
+				data: {
+					policy: {
+						id: policy.id,
+						domain: params.domain,
+						version: policy.version,
+						content: policy.content,
+						availablePreferences: params.includePreferences
+							? //@ts-expect-error
+								policy.availablePreferences
+							: undefined,
+						createdAt: policy.createdAt.toISOString(),
+					},
+				},
+			};
+
+			// If subject identifiers were provided, try to find the subject's consent status
+			if (params.subjectId || params.externalId || params.ipAddress) {
+				let subjectRecord: EntityOutputFields<'subject'> | null = null;
+				let identifierUsed: string | null = null;
+
+				// Try to find subject by subjectId
+				if (params.subjectId) {
+					subjectRecord = await registry.findSubjectById(params.subjectId);
+					if (subjectRecord) {
+						identifierUsed = 'subjectId';
+					}
+				}
+
+				// If not found and externalId provided, try that
+				if (!subjectRecord && params.externalId) {
+					subjectRecord = await registry.findSubjectByExternalId(
+						params.externalId
+					);
+					if (subjectRecord) {
+						identifierUsed = 'externalId';
+					}
+				}
+
+				// If we found a subject, get their consent status
+				if (subjectRecord) {
+					// Get subject's active consents for this domain
+					const subjectConsents = await registry.findConsents({
+						subjectId: subjectRecord.id,
+						domainId: domain.id,
+						status: 'active',
+					});
+
+					// Get the latest active consent
+					const subjectConsent =
+						subjectConsents.length > 0 ? subjectConsents[0] : null;
+
+					// Add subject consent info to response
+					response.data.subjectConsentStatus = {
+						hasConsent: !!subjectConsent,
+						currentPreferences: subjectConsent
+							? // @ts-expect-error
+								subjectConsent.preferences
+							: null,
+						consentedAt: subjectConsent
+							? subjectConsent.givenAt.toISOString() || null
+							: null,
+						needsRenewal: subjectConsent
+							? subjectConsent.policyId !== policy.id
+							: true,
+						identifiedBy: identifierUsed,
+					};
+				}
+			}
+
+			return response;
+		} catch (error) {
+			const context = ctx.context as C15TContext;
+			context.logger?.error?.('Error getting consent policy:', error);
+
+			if (error instanceof C15TError) {
+				throw error;
+			}
+			if (error instanceof z.ZodError) {
+				throw new C15TError('BAD_REQUEST', {
+					code: BASE_ERROR_CODES.BAD_REQUEST,
+					status: 400,
+					data: {
+						message: 'Invalid request data',
+						details: error.errors,
+					},
+				});
+			}
+
+			throw new C15TError('INTERNAL_SERVER_ERROR', {
+				code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+				status: 503,
+				data: {
+					message: 'Failed to get consent policy',
+					details:
+						error instanceof Error ? { message: error.message } : { error },
+				},
+			});
+		}
+	}
+);

package/src/api/routes/get-consent.ts

@@ -0,0 +1,230 @@
+import { z } from 'zod';
+import type { EntityOutputFields } from '~/db/schema/definition';
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { C15TContext } from '../../types';
+import { createAuthEndpoint } from '../call';
+
+// Define schemas for the different identification methods
+const getBySubjectIdSchema = z.object({
+	subjectId: z.string(),
+	domain: z.string().optional(),
+	identifierType: z.literal('subjectId'),
+});
+
+const getByExternalIdSchema = z.object({
+	externalId: z.string(),
+	domain: z.string().optional(),
+	identifierType: z.literal('externalId'),
+});
+
+const getByIpAddressSchema = z.object({
+	ipAddress: z.string(),
+	domain: z.string(),
+	identifierType: z.literal('ipAddress'),
+});
+
+// Combined schema using discriminated union
+const getConsentSchema = z.discriminatedUnion('identifierType', [
+	getBySubjectIdSchema,
+	getByExternalIdSchema,
+	getByIpAddressSchema,
+]);
+
+export interface GetConsentResponse {
+	success: boolean;
+	data: {
+		hasActiveConsent: boolean;
+		records: Array<{
+			id: string;
+			subjectId: string;
+			domain: string;
+			status: string;
+			givenAt: string;
+			policyId: string;
+			preferences: Record<string, string | null>;
+		}>;
+		identifiedBy: string | null;
+	};
+}
+
+/**
+ * Endpoint for retrieving active consent records.
+ *
+ * This endpoint allows clients to retrieve a subject's active consent records by specifying:
+ * 1. The subject ID (internal UUID) and an optional domain
+ * 2. The external ID and an optional domain
+ * 3. The IP address and a required domain (since IP alone is too broad)
+ *
+ * @endpoint GET /consent/get
+ */
+export const getConsent = createAuthEndpoint(
+	'/consent/get',
+	{
+		method: 'GET',
+		query: getConsentSchema,
+	},
+	async (ctx) => {
+		try {
+			const validatedData = getConsentSchema.safeParse(ctx.query);
+
+			if (!validatedData.success) {
+				throw new C15TError(
+					'The request data is invalid. Please ensure all required fields are correctly filled and formatted.',
+					{
+						code: BASE_ERROR_CODES.BAD_REQUEST,
+						status: 400,
+						data: {
+							details: validatedData.error.errors,
+						},
+					}
+				);
+			}
+
+			const params = validatedData.data;
+			const { registry } = ctx.context as C15TContext;
+
+			if (!registry) {
+				throw new C15TError(
+					'The registry service is currently unavailable. Please check the service status and try again later.',
+					{
+						code: BASE_ERROR_CODES.INITIALIZATION_FAILED,
+						status: 503,
+					}
+				);
+			}
+
+			// Find subject based on identifier type
+			let subjects: EntityOutputFields<'subject'>[] = [];
+
+			// biome-ignore lint/style/useDefaultSwitchClause: <explanation>
+			switch (params.identifierType) {
+				case 'subjectId': {
+					const subjectRecord = await registry.findSubjectById(
+						params.subjectId
+					);
+					if (subjectRecord) {
+						subjects = [subjectRecord];
+					}
+					break;
+				}
+				case 'externalId': {
+					const externalSubject = await registry.findSubjectByExternalId(
+						params.externalId
+					);
+					if (externalSubject) {
+						subjects = [externalSubject];
+					}
+					break;
+				}
+				case 'ipAddress': {
+					// For IP address lookups, we require a domain
+					if (!params.domain) {
+						throw new C15TError(
+							'A domain must be specified when using an IP address for identification. Please include a valid domain in your request.',
+							{
+								code: BASE_ERROR_CODES.MISSING_REQUIRED_PARAMETER,
+								status: 400,
+								data: {
+									ipAddress: params.ipAddress,
+								},
+							}
+						);
+					}
+
+					// This is a simplification - in a real implementation, we would need
+					// a method to look up subjects by IP address, possibly by scanning recent consent records
+					// For now, we'll use an empty array as this would require a custom query
+					subjects = [];
+					break;
+				}
+			}
+
+			if (subjects.length === 0) {
+				return {
+					success: true,
+					data: {
+						hasActiveConsent: false,
+						records: [],
+						identifiedBy: params.identifierType,
+					},
+				};
+			}
+
+			// Get active consent records for these subjects
+			const consentResults: Array<{
+				id: string;
+				subjectId: string;
+				domain: string;
+				status: string;
+				givenAt: string;
+			}> = [];
+
+			for (const subject of subjects) {
+				// Use the adapter to find subject consents
+				const subjectConsents = await registry.findConsents({
+					subjectId: subject.id,
+					domainId: params.domain,
+				});
+
+				// Filter for active consents only
+				const activeConsents = subjectConsents.filter(
+					(consent) => consent.status === 'active'
+				);
+
+				// Include subject identification in the results
+				for (const consent of activeConsents) {
+					consentResults.push({
+						id: consent.id,
+						subjectId: subject.id,
+						// domain: consent.domainId,
+						// status: consent.status,
+						givenAt: consent.givenAt.toISOString(),
+						// policyId: consent.policyId || '',
+						//@ts-expect-error
+						preferences: consent.preferences || {},
+					});
+				}
+			}
+
+			return {
+				success: true,
+				data: {
+					hasActiveConsent: consentResults.length > 0,
+					records: consentResults,
+					identifiedBy: params.identifierType,
+				},
+			};
+		} catch (error) {
+			const context = ctx.context as C15TContext;
+			context.logger?.error?.('Error getting consent:', error);
+
+			if (error instanceof C15TError) {
+				throw error;
+			}
+			if (error instanceof z.ZodError) {
+				throw new C15TError(
+					'The request data is invalid. Please ensure all required fields are correctly filled and formatted.',
+					{
+						code: BASE_ERROR_CODES.BAD_REQUEST,
+						status: 400,
+						data: {
+							details: error.errors,
+						},
+					}
+				);
+			}
+
+			throw new C15TError(
+				'Failed to retrieve consent information. Please try again later or contact support if the issue persists.',
+				{
+					code: BASE_ERROR_CODES.FAILED_TO_GET_CONSENT,
+					status: 503,
+					data: {
+						details:
+							error instanceof Error ? { message: error.message } : { error },
+					},
+				}
+			);
+		}
+	}
+);

package/src/api/routes/index.ts

@@ -0,0 +1,12 @@
+import { setConsent } from './set-consent';
+import { status } from './status';
+import { showConsentBanner } from './show-consent-banner';
+
+export * from './error';
+export * from './ok';
+
+export const baseEndpoints = {
+	setConsent,
+	showConsentBanner,
+	status,
+};

package/src/api/routes/ok.ts

@@ -0,0 +1,45 @@
+import { HIDE_METADATA } from '~/utils/hide-metadata';
+import { createAuthEndpoint } from '../call';
+
+export const ok = createAuthEndpoint(
+	'/ok',
+	{
+		method: 'GET',
+		metadata: {
+			...HIDE_METADATA,
+			openapi: {
+				description: 'Check if the API is working',
+				responses: {
+					'200': {
+						description: 'Success',
+						content: {
+							'application/json': {
+								schema: {
+									type: 'object',
+									properties: {
+										ok: {
+											type: 'boolean',
+										},
+										version: {
+											type: 'string',
+										},
+										timestamp: {
+											type: 'string',
+										},
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		},
+	},
+	async (ctx) => {
+		return ctx.json({
+			ok: true,
+			version: process.env.API_VERSION || '1.0.0',
+			timestamp: new Date().toISOString(),
+		});
+	}
+);