@c15t/backend 0.0.1-rc.10

package/src/db/schema/consent/table.ts

@@ -0,0 +1,220 @@
+import type { Field } from '~/db/core/fields';
+import type { C15TOptions } from '~/types';
+import { consentSchema } from './schema';
+/**
+ * Generates the database table configuration for the consent entity.
+ *
+ * This function creates a schema definition that includes all standard consent fields
+ * and any additional fields from plugins or configuration. The resulting schema is used
+ * for database migrations, schema validation, and query building.
+ *
+ * @param options - C15T configuration options that may contain consent table customizations
+ * @param consentFields - Additional fields from plugins to include in the consent table
+ * @returns A complete table schema definition with fields, model name, and metadata
+ *
+ * @example
+ * ```typescript
+ * const consentTableSchema = getConsentTable(c15tOptions);
+ * // Use the schema for migrations or data access
+ * const migrationPlans = generateMigrations(consentTableSchema);
+ * ```
+ */
+export function getConsentTable(
+	options: C15TOptions,
+	consentFields?: Record<string, Field>
+) {
+	// Get consent config from the tables structure
+	const consentConfig = options.tables?.consent;
+	const subjectConfig = options.tables?.subject;
+	const domainConfig = options.tables?.domain;
+	const policyConfig = options.tables?.consentPolicy;
+	const purposeConfig = options.tables?.consentPurpose;
+
+	return {
+		/**
+		 * The name of the consent table in the database, configurable through options
+		 */
+		entityName: consentConfig?.entityName || 'consent',
+
+		/**
+		 * The ID prefix for the consent table
+		 * Used to generate unique prefixed IDs for consents
+		 */
+		entityPrefix: consentConfig?.entityPrefix || 'cns',
+
+		/**
+		 * The schema for the consent table
+		 */
+		schema: consentSchema,
+
+		/**
+		 * Field definitions for the consent table
+		 */
+		fields: {
+			/**
+			 * Reference to the subject who gave consent
+			 */
+			subjectId: {
+				type: 'string',
+				required: true,
+				fieldName: consentConfig?.fields?.subjectId || 'subjectId',
+				references: {
+					model: subjectConfig?.entityName || 'subject',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * Reference to the domain this consent applies to
+			 */
+			domainId: {
+				type: 'string',
+				required: true,
+				fieldName: consentConfig?.fields?.domainId || 'domainId',
+				references: {
+					model: domainConfig?.entityName || 'domain',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * Array of consentPurpose IDs that this consent applies to
+			 * Represents the many-to-many relationship between consent and purposes
+			 */
+			purposeIds: {
+				type: 'json',
+				required: false,
+				fieldName: consentConfig?.fields?.purposeIds || 'purposeIds',
+				references: {
+					model: purposeConfig?.entityName || 'consentPurpose',
+					field: 'id',
+					type: 'array', // Indicates this is an array of references
+				},
+			},
+
+			/**
+			 * Additional metadata about the consent
+			 */
+			metadata: {
+				type: 'json',
+				required: false,
+				fieldName: consentConfig?.fields?.metadata || 'metadata',
+			},
+
+			/**
+			 * Reference to the policy version that was accepted
+			 */
+			policyId: {
+				type: 'string',
+				required: false,
+				fieldName: consentConfig?.fields?.policyId || 'policyId',
+				references: {
+					model: policyConfig?.entityName || 'consentPolicy',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * IP address when consent was given
+			 */
+			ipAddress: {
+				type: 'string',
+				required: false,
+				fieldName: consentConfig?.fields?.ipAddress || 'ipAddress',
+			},
+
+			/**
+			 * Subject agent information when consent was given
+			 */
+			userAgent: {
+				type: 'string',
+				required: false,
+				fieldName: consentConfig?.fields?.userAgent || 'userAgent',
+			},
+
+			/**
+			 * Status of the consent (active, expired, withdrawn)
+			 * Default: 'active'
+			 */
+			status: {
+				type: 'string',
+				defaultValue: () => 'active',
+				required: true,
+				fieldName: consentConfig?.fields?.status || 'status',
+			},
+
+			/**
+			 * Reason for consentWithdrawal, if consent was withdrawn
+			 */
+			withdrawalReason: {
+				type: 'string',
+				required: false,
+				fieldName:
+					consentConfig?.fields?.withdrawalReason || 'withdrawalReason',
+			},
+
+			/**
+			 * When the consent was given
+			 * Automatically set to current time
+			 */
+			givenAt: {
+				type: 'date',
+				defaultValue: () => new Date(),
+				required: true,
+				fieldName: consentConfig?.fields?.givenAt || 'givenAt',
+			},
+
+			/**
+			 * When the consent expires
+			 * Calculated based on givenAt + expiresIn setting
+			 */
+			validUntil: {
+				type: 'date',
+				required: false,
+				fieldName: consentConfig?.fields?.validUntil || 'validUntil',
+				transform: {
+					input: (val: Date | undefined, data: Record<string, unknown>) => {
+						if (val) {
+							return val;
+						}
+
+						const expiresIn = consentConfig?.expiresIn || 31536000; // Default: 1 year
+						const givenAt =
+							data.givenAt instanceof Date ? data.givenAt : new Date();
+
+						if (expiresIn > 0) {
+							const validUntil = new Date(givenAt);
+							validUntil.setSeconds(validUntil.getSeconds() + expiresIn);
+							return validUntil;
+						}
+
+						return undefined; // No expiration
+					},
+				},
+			},
+
+			/**
+			 * Whether the consent is active
+			 * Default: true
+			 */
+			isActive: {
+				type: 'boolean',
+				defaultValue: true,
+				required: true,
+				fieldName: consentConfig?.fields?.isActive || 'isActive',
+			},
+
+			// Include additional fields from plugins
+			...(consentFields || {}),
+
+			// Include additional fields from configuration
+			...(consentConfig?.additionalFields || {}),
+		},
+
+		/**
+		 * Execution order during migrations (lower numbers run first)
+		 * Consent table needs to be created after the subject, domain, and policy tables it references
+		 */
+		order: 3,
+	};
+}

package/src/db/schema/consent/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Consent Entity Type Definitions
+ *
+ * This module contains type definitions specific to the consent entity.
+ */
+import type { BaseEntityConfig } from '../types';
+
+/**
+ * Consent entity configuration
+ * @default entityName: "consent", entityPrefix: "cns"
+ */
+export interface ConsentEntityConfig extends BaseEntityConfig {
+	/**
+	 * Default expiration for consent in seconds
+	 * @default 31536000 (1 year)
+	 */
+	expiresIn?: number;
+
+	/**
+	 * Time in seconds before refreshing consent data
+	 * @default 86400 (24 hours)
+	 */
+	updateAge?: number;
+
+	fields?: Record<string, string> & {
+		id?: string;
+		subjectId?: string;
+		domainId?: string;
+		purposeIds?: string;
+		metadata?: string;
+		policyId?: string;
+		ipAddress?: string;
+		userAgent?: string;
+		status?: string;
+		withdrawalReason?: string;
+		givenAt?: string;
+		validUntil?: string;
+	};
+}

package/src/db/schema/consent-geo-location/index.ts

@@ -0,0 +1,3 @@
+export * from './registry';
+export * from './schema';
+export * from './table';

package/src/db/schema/consent-geo-location/registry.ts

@@ -0,0 +1,124 @@
+import { getWithHooks } from '~/db/hooks';
+import type { GenericEndpointContext, RegistryContext } from '~/types';
+import { validateEntityOutput } from '../definition';
+import type { ConsentGeoLocation } from './schema';
+
+/**
+ * Creates and returns a set of consent geo-location-related adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating and finding
+ * geo-location records while applying hooks and enforcing data validation rules.
+ *
+ * @param adapter - The database adapter used for direct database operations
+ * @param ctx - The context object containing the database adapter, hooks, and options
+ * @returns An object containing type-safe consent geo-location operations
+ *
+ * @example
+ * ```typescript
+ * const geoLocationAdapter = createConsentGeoLocationAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new geo-location record
+ * const geoLocation = await geoLocationAdapter.createConsentGeoLocation({
+ *   consentId: 'cns_hadt8w7nngm7xmx2bn',
+ *   ip: '192.168.1.1',
+ *   country: 'US',
+ *   city: 'New York',
+ *   latitude: 40.7128,
+ *   longitude: -74.0060
+ * });
+ * ```
+ */
+export function consentGeoLocationRegistry({
+	adapter,
+	...ctx
+}: RegistryContext) {
+	const { createWithHooks } = getWithHooks(adapter, ctx);
+
+	return {
+		/**
+		 * Creates a new consent geo-location record in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param geoLocation - Geo-location data to create (without id and timestamp)
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The created geo-location record with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		createConsentGeoLocation: async (
+			geoLocation: Omit<ConsentGeoLocation, 'id' | 'createdAt'> &
+				Partial<ConsentGeoLocation>,
+			context?: GenericEndpointContext
+		) => {
+			const createdGeoLocation = await createWithHooks({
+				data: {
+					createdAt: new Date(),
+					...geoLocation,
+				},
+				model: 'consentGeoLocation',
+				customFn: undefined,
+				context,
+			});
+
+			if (!createdGeoLocation) {
+				throw new Error(
+					'Failed to create consent geo-location - operation returned null'
+				);
+			}
+
+			return createdGeoLocation as ConsentGeoLocation;
+		},
+
+		/**
+		 * Finds geo-location records associated with a specific consent ID.
+		 * Returns geo-locations with processed output fields according to the schema configuration.
+		 *
+		 * @param consentId - The ID of the consent record to find geo-locations for
+		 * @returns Array of geo-location records associated with the consent
+		 */
+		findConsentGeoLocationsByConsentId: async (consentId: string) => {
+			const geoLocations = await adapter.findMany({
+				model: 'consentGeoLocation',
+				where: [
+					{
+						field: 'consentId',
+						value: consentId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+			});
+
+			return geoLocations.map((geoLocation) =>
+				validateEntityOutput('consentGeoLocation', geoLocation, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds a geo-location record by its unique ID.
+		 * Returns the geo-location with processed output fields according to the schema configuration.
+		 *
+		 * @param geoLocationId - The unique identifier of the geo-location record
+		 * @returns The geo-location object if found, null otherwise
+		 */
+		findConsentGeoLocationById: async (geoLocationId: string) => {
+			const geoLocation = await adapter.findOne({
+				model: 'consentGeoLocation',
+				where: [
+					{
+						field: 'id',
+						value: geoLocationId,
+					},
+				],
+			});
+			return geoLocation
+				? validateEntityOutput('consentGeoLocation', geoLocation, ctx.options)
+				: null;
+		},
+	};
+}

package/src/db/schema/consent-geo-location/schema.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for validating consent geo-location entities.
+ *
+ * This defines the structure and validation rules for geo-location records:
+ * - Required fields: consentId, ip (IP address)
+ * - Optional fields: country, region, city, latitude, longitude, timezone
+ * - Default current date/time for creation and update timestamps
+ *
+ * @example
+ * ```typescript
+ * const geoLocationData = {
+ *   id: 'cgl_w5qufx2a66m7xkn3ty',
+ *   consentId: 'cns_hadt8w7nngm7xmx2bn',
+ *   ip: '192.168.1.1',
+ *   country: 'US',
+ *   city: 'New York',
+ *   latitude: 40.7128,
+ *   longitude: -74.0060
+ * };
+ *
+ * // Validate and parse the geo-location data
+ * const validGeoLocation = consentGeoLocationSchema.parse(geoLocationData);
+ * ```
+ */
+export const consentGeoLocationSchema = z.object({
+	id: z.string(),
+	consentId: z.string(),
+	ip: z.string().ip(),
+	country: z.string().optional(),
+	region: z.string().optional(),
+	city: z.string().optional(),
+	latitude: z.number().min(-90).max(90).optional(),
+	longitude: z.number().min(-180).max(180).optional(),
+	timezone: z
+		.string()
+		.regex(/^[A-Za-z_]+\/[A-Za-z_]+$/)
+		.optional(), // Basic IANA timezone format check
+	createdAt: z.date().default(() => new Date()),
+	updatedAt: z.date().default(() => new Date()),
+});
+
+/**
+ * Type definition for ConsentGeoLocation
+ *
+ * This type represents the structure of a consent geo-location record
+ * as defined by the consentGeoLocationSchema. It includes all fields
+ * that are part of the consent geo-location entity.
+ */
+export type ConsentGeoLocation = z.infer<typeof consentGeoLocationSchema>;

package/src/db/schema/consent-geo-location/table.ts

@@ -0,0 +1,169 @@
+import type { Field } from '~/db/core/fields';
+import type { C15TOptions } from '~/types';
+import { consentGeoLocationSchema } from './schema';
+
+/**
+ * Generates the database table configuration for the consent geo-location entity.
+ *
+ * This function creates a schema definition that includes all standard geo-location fields
+ * and any additional fields from plugins or configuration. The resulting schema is used
+ * for database migrations, schema validation, and query building.
+ *
+ * @param options - C15T configuration options that may contain geo-location table customizations
+ * @param geoLocationFields - Additional fields from plugins to include in the geo-location table
+ * @returns A complete table schema definition with fields, model name, and metadata
+ *
+ * @example
+ * ```typescript
+ * const geoLocationTableSchema = getConsentGeoLocationTable(c15tOptions);
+ * // Use the schema for migrations or data access
+ * const migrationPlans = generateMigrations(geoLocationTableSchema);
+ * ```
+ */
+export function getConsentGeoLocationTable(
+	options: C15TOptions,
+	geoLocationFields?: Record<string, Field>
+) {
+	const consentGeoLocationConfig = options.tables?.consentGeoLocation;
+	const consentConfig = options.tables?.consent;
+
+	return {
+		/**
+		 * The name of the geo-location table in the database, configurable through options
+		 */
+		entityName: consentGeoLocationConfig?.entityName || 'consentGeoLocation',
+
+		/**
+		 * The ID prefix for the consent geo-location table
+		 * Used to generate unique prefixed IDs for consent geo-locations
+		 */
+		entityPrefix: consentGeoLocationConfig?.entityPrefix || 'cgl',
+
+		/**
+		 * The schema for the consent geo-location table
+		 */
+		schema: consentGeoLocationSchema,
+
+		/**
+		 * Field definitions for the consent geo-location table
+		 */
+		fields: {
+			/**
+			 * Reference to the consent record this geo-location is associated with
+			 */
+			consentId: {
+				type: 'string',
+				required: true,
+				fieldName: consentGeoLocationConfig?.fields?.consentId || 'consentId',
+				references: {
+					model: consentConfig?.entityName || 'consent',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * IP address from which the consent was given
+			 */
+			ip: {
+				type: 'string',
+				required: true,
+				fieldName: consentGeoLocationConfig?.fields?.ip || 'ip',
+			},
+
+			/**
+			 * Country code (e.g., 'US', 'DE', 'FR')
+			 */
+			country: {
+				type: 'string',
+				required: false,
+				fieldName: consentGeoLocationConfig?.fields?.country || 'country',
+			},
+
+			/**
+			 * Region or state (e.g., 'California', 'Bavaria')
+			 */
+			region: {
+				type: 'string',
+				required: false,
+				fieldName: consentGeoLocationConfig?.fields?.region || 'region',
+			},
+
+			/**
+			 * City name (e.g., 'New York', 'Berlin')
+			 */
+			city: {
+				type: 'string',
+				required: false,
+				fieldName: consentGeoLocationConfig?.fields?.city || 'city',
+			},
+
+			/**
+			 * Latitude coordinate
+			 */
+			latitude: {
+				type: 'number',
+				required: false,
+				fieldName: consentGeoLocationConfig?.fields?.latitude || 'latitude',
+			},
+
+			/**
+			 * Longitude coordinate
+			 */
+			longitude: {
+				type: 'number',
+				required: false,
+				fieldName: consentGeoLocationConfig?.fields?.longitude || 'longitude',
+			},
+
+			/**
+			 * Timezone identifier (e.g., 'America/New_York', 'Europe/Berlin')
+			 */
+			timezone: {
+				type: 'string',
+				required: false,
+				fieldName: consentGeoLocationConfig?.fields?.timezone || 'timezone',
+			},
+
+			/**
+			 * When the geo-location record was created
+			 * Automatically set to current time by default
+			 */
+			createdAt: {
+				type: 'date',
+				defaultValue: () => new Date(),
+				required: true,
+				fieldName: consentGeoLocationConfig?.fields?.createdAt || 'createdAt',
+			},
+
+			// Include additional fields from plugins
+			...(geoLocationFields || {}),
+
+			// Include additional fields from configuration
+			...(consentGeoLocationConfig?.additionalFields || {}),
+		},
+
+		/**
+		 * Add indexes for better query performance
+		 */
+		indexes: [
+			{
+				name: 'consent_id_index',
+				fields: ['consentId'],
+			},
+			{
+				name: 'country_index',
+				fields: ['country'],
+			},
+			{
+				name: 'created_at_index',
+				fields: ['createdAt'],
+			},
+		],
+
+		/**
+		 * Execution order during migrations (lower numbers run first)
+		 * Geo-location table needs to be created after the consent table it references
+		 */
+		order: 4,
+	};
+}

package/src/db/schema/consent-geo-location/types.ts

@@ -0,0 +1,21 @@
+import type { BaseEntityConfig } from '../types';
+
+/**
+ * Consent geo location entity configuration
+ * @default entityName: "consentGeoLocation", entityPrefix: "cgl"
+ */
+export interface ConsentGeoLocationEntityConfig extends BaseEntityConfig {
+	fields?: Record<string, string> & {
+		id?: string;
+		/**
+		 * Indicates if the domain is a pattern (e.g., "true"/"false")
+		 * When true, the domain string will be interpreted as a pattern
+		 */
+		consentId?: string;
+		/**
+		 * Foreign key to geo-location entity (should be indexed)
+		 */
+		geoLocationId?: string;
+		createdAt?: string;
+	};
+}

package/src/db/schema/consent-policy/index.ts

@@ -0,0 +1,3 @@
+export * from './registry';
+export * from './schema';
+export * from './table';