@c15t/backend 0.0.1-rc.10

package/src/db/schema/domain/registry.ts

@@ -0,0 +1,272 @@
+import type { Where } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks';
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { GenericEndpointContext, RegistryContext } from '~/types';
+import { validateEntityOutput } from '../definition';
+import type { Domain } from './schema';
+
+export interface FindDomainParams {
+	name?: string;
+	includeInactive?: boolean;
+}
+
+/**
+ * Creates and returns a set of domain-related adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating, finding, and updating
+ * domain 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 domain operations
+ *
+ * @example
+ * ```typescript
+ * const domainAdapter = createDomainAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   updateWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new domain
+ * const domain = await domainAdapter.createDomain({
+ *   name: 'example.com',
+ *   description: 'Example company website',
+ *   isVerified: true
+ * });
+ * ```
+ */
+export function domainRegistry({ adapter, ...ctx }: RegistryContext) {
+	const { createWithHooks, updateWithHooks } = getWithHooks(adapter, ctx);
+	const registry = {
+		/**
+		 * Creates a new domain record in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param domain - Domain data to create (without id and timestamp)
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The created domain with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		createDomain: async (
+			domain: Omit<Domain, 'id' | 'createdAt' | 'updatedAt'> & Partial<Domain>,
+			context?: GenericEndpointContext
+		) => {
+			const createdDomain = await createWithHooks({
+				data: {
+					...domain,
+					createdAt: new Date(),
+					updatedAt: new Date(),
+				},
+				model: 'domain',
+				customFn: undefined,
+				context,
+			});
+
+			if (!createdDomain) {
+				throw new Error('Failed to create domain - operation returned null');
+			}
+
+			return createdDomain as Domain;
+		},
+
+		/**
+		 * Finds an existing domain or creates a new one if needed.
+		 *
+		 * @param name - The domain name to find or create
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The existing or newly created domain
+		 * @throws APIError if domain creation fails
+		 */
+		findOrCreateDomain: async function (
+			name: string,
+			context?: GenericEndpointContext
+		) {
+			// Try to find existing domain
+			const existingDomain = await this.findDomainByName(name);
+			if (existingDomain) {
+				return existingDomain;
+			}
+
+			// Create new domain if not found
+			const domain = await this.createDomain(
+				{
+					name,
+					description: `Auto-created domain for ${name}`,
+					isActive: true,
+					isVerified: true,
+					allowedOrigins: [],
+				},
+				context
+			);
+
+			if (!domain) {
+				throw new C15TError('Failed to create domain', {
+					code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+					status: 503,
+				});
+			}
+
+			return domain;
+		},
+
+		/**
+		 * Finds all domains, optionally including inactive ones.
+		 * Returns domains with processed output fields according to the schema configuration.
+		 *
+		 * @param params - Optional parameters to filter the results
+		 * @returns Array of domains matching the criteria
+		 */
+		findDomains: async (params: FindDomainParams = {}) => {
+			const whereConditions: Where<'domain'> = [];
+
+			if (!params.includeInactive) {
+				whereConditions.push({
+					field: 'isActive',
+					value: true,
+				});
+			}
+
+			if (params.name) {
+				whereConditions.push({
+					field: 'name',
+					value: params.name,
+				});
+			}
+
+			const domains = await adapter.findMany({
+				model: 'domain',
+				where: whereConditions,
+				sortBy: {
+					field: 'name',
+					direction: 'asc',
+				},
+			});
+
+			return domains.map((domain) =>
+				validateEntityOutput('domain', domain, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds a domain by its name.
+		 * Returns the domain with processed output fields according to the schema configuration.
+		 *
+		 * @param name - The domain name to search for
+		 * @returns The domain object if found, null otherwise
+		 */
+		findDomain: async (name: string) => {
+			const domains = await registry.findDomains({
+				name,
+				includeInactive: false,
+			});
+			return domains[0] || null;
+		},
+
+		/**
+		 * Finds a domain by its unique ID.
+		 * Returns the domain with processed output fields according to the schema configuration.
+		 *
+		 * @param domainId - The unique identifier of the domain
+		 * @returns The domain object if found, null otherwise
+		 */
+		findDomainById: async (domainId: string) => {
+			const domain = await adapter.findOne({
+				model: 'domain',
+				where: [
+					{
+						field: 'id',
+						value: domainId,
+					},
+				],
+			});
+			return domain
+				? validateEntityOutput('domain', domain, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Finds a domain by its name.
+		 * Returns the domain with processed output fields according to the schema configuration.
+		 *
+		 * @param name - The domain name to search for
+		 * @returns The domain object if found, null otherwise
+		 */
+		findDomainByName: async (name: string) => {
+			const domain = await adapter.findOne({
+				model: 'domain',
+				where: [
+					{
+						field: 'name',
+						value: name,
+					},
+				],
+			});
+			return domain
+				? validateEntityOutput('domain', domain, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Updates an existing domain record by ID.
+		 * Applies any configured hooks during the update process and
+		 * processes the output according to schema configuration.
+		 *
+		 * @param domainId - The unique identifier of the domain to update
+		 * @param data - The fields to update on the domain record
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The updated domain if successful, null if not found or hooks prevented update
+		 */
+		updateDomain: async (
+			domainId: string,
+			data: Partial<Domain>,
+			context?: GenericEndpointContext
+		) => {
+			const domain = await updateWithHooks({
+				data: {
+					...data,
+					updatedAt: new Date(),
+				},
+				where: [
+					{
+						field: 'id',
+						value: domainId,
+					},
+				],
+				model: 'domain',
+				customFn: undefined,
+				context,
+			});
+			return domain
+				? validateEntityOutput('domain', domain as Domain, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Verifies if a domain exists and is active.
+		 * Useful for checking domain validity during API requests.
+		 *
+		 * @param domainName - The domain name to verify
+		 * @returns True if the domain exists and is active, false otherwise
+		 */
+		verifyDomain: async (domainName: string) => {
+			const domain = await adapter.findOne({
+				model: 'domain',
+				where: [
+					{
+						field: 'name',
+						value: domainName,
+					},
+					{
+						field: 'isActive',
+						value: true,
+					},
+				],
+			});
+			return !!domain;
+		},
+	};
+
+	return registry;
+}

package/src/db/schema/domain/schema.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for validating domain entities.
+ *
+ * This defines the structure and validation rules for domain records:
+ * - Required fields: name
+ * - Optional fields: description, allowedOrigins
+ * - Default value of true for isActive and isVerified
+ * - Default current date/time for creation timestamp
+ *
+ * @example
+ * ```typescript
+ * const domainData = {
+ *   id: 'dom_x1pftyoufsm7xgo1kv',
+ *   name: 'example.com',
+ *   description: 'Company website',
+ *   allowedOrigins: ['https://app.example.com', 'https://admin.example.com']
+ * };
+ *
+ * // Validate and parse the domain data
+ * const validDomain = domainSchema.parse(domainData);
+ * ```
+ */
+export const domainSchema = z.object({
+	id: z.string(),
+	name: z.string().min(1),
+	description: z.string().optional(),
+	allowedOrigins: z.array(z.string()).optional().default([]),
+	isVerified: z.boolean().default(true),
+	isActive: z.boolean().default(true),
+	createdAt: z.date().default(() => new Date()),
+	updatedAt: z.date().default(() => new Date()),
+});
+
+/**
+ * Type definition for Domain
+ *
+ * This type represents the structure of a domain record
+ * as defined by the domainSchema. It includes all fields
+ * that are part of the domain entity.
+ */
+export type Domain = z.infer<typeof domainSchema>;

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

@@ -0,0 +1,137 @@
+import type { Field } from '~/db/core/fields';
+import type { C15TOptions } from '~/types';
+import { domainSchema } from './schema';
+
+/**
+ * Generates the database table configuration for the domain entity.
+ *
+ * This function creates a schema definition that includes all standard domain 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 domain table customizations
+ * @param domainFields - Additional fields from plugins to include in the domain table
+ * @returns A complete table schema definition with fields, model name, and metadata
+ *
+ * @example
+ * ```typescript
+ * const domainTableSchema = getDomainTable(c15tOptions);
+ * // Use the schema for migrations or data access
+ * const migrationPlans = generateMigrations(domainTableSchema);
+ * ```
+ */
+export function getDomainTable(
+	options: C15TOptions,
+	domainFields?: Record<string, Field>
+) {
+	const domainConfig = options.tables?.domain;
+
+	return {
+		/**
+		 * The name of the domain table in the database, configurable through options
+		 */
+		entityName: domainConfig?.entityName || 'domain',
+
+		/**
+		 * The ID prefix for the domain table
+		 * Used to generate unique prefixed IDs for domains
+		 */
+		entityPrefix: domainConfig?.entityPrefix || 'dom',
+
+		/**
+		 * The schema for the domain table
+		 */
+		schema: domainSchema,
+
+		/**
+		 * Field definitions for the domain table
+		 */
+		fields: {
+			/**
+			 * Domain name (e.g., "example.com")
+			 * This is the primary identifier for the domain in addition to its ID
+			 */
+			name: {
+				type: 'string',
+				required: true,
+				unique: true,
+				fieldName: domainConfig?.fields?.name || 'name',
+			},
+
+			/**
+			 * Optional human-readable description of the domain
+			 */
+			description: {
+				type: 'string',
+				required: false,
+				fieldName: domainConfig?.fields?.description || 'description',
+			},
+
+			/**
+			 * List of additional origins that are allowed to access resources for this domain
+			 * Stored as a JSON array of strings
+			 */
+			allowedOrigins: {
+				type: 'json',
+				defaultValue: () => [],
+				required: false,
+				fieldName: domainConfig?.fields?.allowedOrigins || 'allowedOrigins',
+			},
+
+			/**
+			 * Whether domain ownership has been verified
+			 * Default: true
+			 */
+			isVerified: {
+				type: 'boolean',
+				defaultValue: true,
+				required: true,
+				fieldName: domainConfig?.fields?.isVerified || 'isVerified',
+			},
+
+			/**
+			 * Whether this domain is currently active
+			 * Default: true
+			 */
+			isActive: {
+				type: 'boolean',
+				defaultValue: true,
+				required: true,
+				fieldName: domainConfig?.fields?.isActive || 'isActive',
+			},
+
+			/**
+			 * When the domain record was created
+			 * Automatically set to current time by default
+			 */
+			createdAt: {
+				type: 'date',
+				defaultValue: () => new Date(),
+				required: true,
+				fieldName: domainConfig?.fields?.createdAt || 'createdAt',
+			},
+
+			/**
+			 * When the domain record was last updated
+			 * Optional, set during updates
+			 */
+			updatedAt: {
+				type: 'date',
+				required: false,
+				fieldName: domainConfig?.fields?.updatedAt || 'updatedAt',
+			},
+
+			// Include additional fields from plugins
+			...(domainFields || {}),
+
+			// Include additional fields from configuration
+			...(domainConfig?.additionalFields || {}),
+		},
+
+		/**
+		 * Execution order during migrations (lower numbers run first)
+		 * Domain table needs to be created before tables that reference it
+		 */
+		order: 1,
+	};
+}

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

@@ -0,0 +1,27 @@
+import type { ActiveEntityConfig } from '../types';
+
+/**
+ * Domain entity configuration
+ * @default entityName: "domain", entityPrefix: "dom"
+ */
+export interface DomainEntityConfig extends ActiveEntityConfig {
+	fields?: Record<string, string> & {
+		id?: string;
+		domain: string;
+		/**
+		 * Indicates if the domain is a pattern (e.g., "true"/"false")
+		 * When true, the domain string will be interpreted as a pattern
+		 */
+		isPattern?: string;
+		/**
+		 * The type of pattern matching to apply
+		 * Valid values: "regex", "wildcard", "prefix", "suffix", "exact"
+		 */
+		patternType?: string;
+		parentDomainId?: string;
+		description?: string;
+		isActive?: string;
+		createdAt?: string;
+		updatedAt?: string;
+	};
+}

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

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

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

@@ -0,0 +1,159 @@
+import type { Where } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks/with-hooks-factory';
+import type { GenericEndpointContext, RegistryContext } from '~/types';
+import { validateEntityOutput } from '../definition';
+import type { GeoLocation } from './schema';
+/**
+ * Creates and returns a set of 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 geo-location operations
+ *
+ * @example
+ * ```typescript
+ * const locationAdapter = createGeoLocationAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new geo-location record
+ * const location = await locationAdapter.createGeoLocation({
+ *   countryCode: 'US',
+ *   countryName: 'United States',
+ *   regionCode: 'CA',
+ *   regionName: 'California',
+ *   regulatoryZones: ['CCPA', 'CPRA']
+ * });
+ * ```
+ */
+export function geoLocationRegistry({ adapter, ...ctx }: RegistryContext) {
+	const { createWithHooks } = getWithHooks(adapter, ctx);
+	return {
+		/**
+		 * Creates a new geo-location record in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param location - 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
+		 */
+		createGeoLocation: async (
+			location: Omit<GeoLocation, 'id' | 'createdAt'> & Partial<GeoLocation>,
+			context?: GenericEndpointContext
+		) => {
+			const createdLocation = await createWithHooks({
+				data: {
+					createdAt: new Date(),
+					...location,
+				},
+				model: 'consentGeoLocation',
+				customFn: undefined,
+				context,
+			});
+
+			if (!createdLocation) {
+				throw new Error(
+					'Failed to create geo-location - operation returned null'
+				);
+			}
+
+			return createdLocation as GeoLocation;
+		},
+
+		/**
+		 * Finds all geo-location records matching the given criteria.
+		 * Returns geo-locations with processed output fields according to the schema configuration.
+		 *
+		 * @param filter - Optional filter parameters for the query
+		 * @returns Array of geo-location records matching the criteria
+		 */
+		findGeoLocations: async (filter?: {
+			countryCode?: string;
+			regionCode?: string;
+		}) => {
+			const whereConditions: Where<'geoLocation'> = [];
+
+			if (filter?.countryCode) {
+				whereConditions.push({
+					field: 'countryCode',
+					value: filter.countryCode,
+				});
+			}
+
+			if (filter?.regionCode) {
+				whereConditions.push({
+					field: 'regionCode',
+					value: filter.regionCode,
+				});
+			}
+
+			const locations = await adapter.findMany({
+				model: 'geoLocation',
+				where: whereConditions,
+				sortBy: {
+					field: 'countryName',
+					direction: 'asc',
+				},
+			});
+
+			return locations.map((location) =>
+				validateEntityOutput('consentGeoLocation', location, 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 locationId - The unique identifier of the geo-location record
+		 * @returns The geo-location object if found, null otherwise
+		 */
+		findGeoLocationById: async (locationId: string) => {
+			const location = await adapter.findOne({
+				model: 'geoLocation',
+				where: [
+					{
+						field: 'id',
+						value: locationId,
+					},
+				],
+			});
+			return location
+				? validateEntityOutput('consentGeoLocation', location, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Finds geo-location records by country code.
+		 * Returns geo-locations with processed output fields according to the schema configuration.
+		 *
+		 * @param countryCode - The country code to search for
+		 * @returns Array of geo-location records for the specified country
+		 */
+		findGeoLocationsByCountry: async (countryCode: string) => {
+			const locations = await adapter.findMany({
+				model: 'geoLocation',
+				where: [
+					{
+						field: 'countryCode',
+						value: countryCode,
+					},
+				],
+				sortBy: {
+					field: 'regionName',
+					direction: 'asc',
+				},
+			});
+
+			return locations.map((location) =>
+				validateEntityOutput('consentGeoLocation', location, ctx.options)
+			);
+		},
+	};
+}

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

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for validating geo-location entities.
+ *
+ * This defines the structure and validation rules for geographic location records:
+ * - Required fields: countryCode, countryName
+ * - Optional fields: regionCode, regionName, regulatoryZones
+ * - Default current date/time for creation timestamp
+ *
+ * @example
+ * ```typescript
+ * const locationData = {
+ *   id: 'geo_x1pftyoufsm7xgo1kv',
+ *   countryCode: 'US',
+ *   countryName: 'United States',
+ *   regionCode: 'CA',
+ *   regionName: 'California',
+ *   regulatoryZones: ['CCPA', 'CPRA']
+ * };
+ *
+ * // Validate and parse the geo-location data
+ * const validLocation = geoLocationSchema.parse(locationData);
+ * ```
+ */
+export const geoLocationSchema = z.object({
+	id: z.string(),
+	countryCode: z.string().length(2).toUpperCase(),
+	countryName: z.string(),
+	regionCode: z.string().optional(),
+	regionName: z.string().optional(),
+	regulatoryZones: z
+		.array(z.enum(['GDPR', 'CCPA', 'CPRA', 'LGPD', 'PIPEDA']))
+		.optional(), // Add your actual regulatory zones
+	createdAt: z.date().default(() => new Date()),
+});
+
+/**
+ * Type definition for GeoLocation
+ *
+ * This type represents the structure of a geo-location entity
+ * as defined by the geoLocationSchema. It includes all fields
+ * that are part of the geo-location entity.
+ */
+export type GeoLocation = z.infer<typeof geoLocationSchema>;