@htlkg/data 0.0.24 → 0.0.25

package/src/validation/contact.schemas.ts

@@ -0,0 +1,611 @@
+/**
+ * Contact Validation Schemas
+ *
+ * Comprehensive Zod validation schemas for Contact entities.
+ * Includes field-level validators, custom field schemas, and complete entity schemas.
+ *
+ * @module @htlkg/data/validation/contact.schemas
+ */
+
+import { z } from "zod";
+
+// ============================================
+// Field-Level Validators
+// ============================================
+
+/**
+ * Email validation schema
+ * - Must be valid email format
+ * - Transforms to lowercase for consistency
+ * - Max 254 characters (RFC 5321)
+ */
+export const emailSchema = z
+	.string()
+	.trim()
+	.toLowerCase()
+	.email("Invalid email address")
+	.max(254, "Email must not exceed 254 characters");
+
+/**
+ * Optional email validation schema
+ * Same rules as emailSchema but allows undefined
+ */
+export const optionalEmailSchema = z
+	.string()
+	.trim()
+	.toLowerCase()
+	.email("Invalid email address")
+	.max(254, "Email must not exceed 254 characters")
+	.optional();
+
+/**
+ * Phone number validation schema
+ * Supports international formats:
+ * - E.164 format: +14155552671
+ * - With spaces/dashes: +1 415-555-2671
+ * - Local formats: (415) 555-2671
+ * - Minimum 7 digits, maximum 15 digits (ITU-T E.164)
+ */
+const PHONE_REGEX = /^[\+]?[(]?[0-9]{1,4}[)]?[-\s\.]?[(]?[0-9]{1,3}[)]?[-\s\.]?[0-9]{1,4}[-\s\.]?[0-9]{1,4}[-\s\.]?[0-9]{0,9}$/;
+
+export const phoneSchema = z
+	.string()
+	.trim()
+	.min(7, "Phone number must be at least 7 characters")
+	.max(20, "Phone number must not exceed 20 characters")
+	.regex(PHONE_REGEX, "Invalid phone number format");
+
+/**
+ * Optional phone validation schema
+ * Validates format only if value is provided and non-empty
+ */
+export const optionalPhoneSchema = z
+	.string()
+	.trim()
+	.optional()
+	.refine(
+		(val) => {
+			if (!val || val === "") return true;
+			return PHONE_REGEX.test(val) && val.length >= 7 && val.length <= 20;
+		},
+		{ message: "Invalid phone number format" }
+	);
+
+/**
+ * First name validation schema
+ * - Required, 1-100 characters
+ * - Trims whitespace
+ * - Allows Unicode letters, spaces, hyphens, apostrophes
+ */
+const NAME_REGEX = /^[\p{L}\s\-'\.]+$/u;
+
+export const firstNameSchema = z
+	.string()
+	.trim()
+	.min(1, "First name is required")
+	.max(100, "First name must not exceed 100 characters")
+	.regex(NAME_REGEX, "First name contains invalid characters");
+
+/**
+ * Last name validation schema
+ * - Required, 1-100 characters
+ * - Trims whitespace
+ * - Allows Unicode letters, spaces, hyphens, apostrophes
+ */
+export const lastNameSchema = z
+	.string()
+	.trim()
+	.min(1, "Last name is required")
+	.max(100, "Last name must not exceed 100 characters")
+	.regex(NAME_REGEX, "Last name contains invalid characters");
+
+/**
+ * Optional first name validation schema
+ */
+export const optionalFirstNameSchema = z
+	.string()
+	.trim()
+	.min(1, "First name cannot be empty if provided")
+	.max(100, "First name must not exceed 100 characters")
+	.regex(NAME_REGEX, "First name contains invalid characters")
+	.optional();
+
+/**
+ * Optional last name validation schema
+ */
+export const optionalLastNameSchema = z
+	.string()
+	.trim()
+	.min(1, "Last name cannot be empty if provided")
+	.max(100, "Last name must not exceed 100 characters")
+	.regex(NAME_REGEX, "Last name contains invalid characters")
+	.optional();
+
+/**
+ * Locale validation schema (BCP 47 language tag)
+ * Examples: "en", "en-US", "pt-BR", "zh-Hans-CN"
+ */
+const LOCALE_REGEX = /^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$/;
+
+export const localeSchema = z
+	.string()
+	.regex(LOCALE_REGEX, "Invalid locale format. Use BCP 47 format (e.g., 'en', 'en-US', 'pt-BR')");
+
+/**
+ * Optional locale validation schema
+ */
+export const optionalLocaleSchema = z
+	.string()
+	.regex(LOCALE_REGEX, "Invalid locale format. Use BCP 47 format (e.g., 'en', 'en-US', 'pt-BR')")
+	.optional();
+
+/**
+ * ISO 8601 date string regex pattern
+ * Matches: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, YYYY-MM-DDTHH:MM:SSZ, YYYY-MM-DDTHH:MM:SS±HH:MM
+ */
+const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-]\d{2}:\d{2})?)?$/;
+
+/**
+ * ISO 8601 date string validation schema
+ * Validates date strings in ISO 8601 format
+ */
+export const isoDateStringSchema = z
+	.string()
+	.refine(
+		(val) => {
+			// First check format matches ISO 8601
+			if (!ISO_DATE_REGEX.test(val)) return false;
+			// Then verify it's a valid date
+			const date = new Date(val);
+			return !isNaN(date.getTime());
+		},
+		{ message: "Invalid date format. Use ISO 8601 format (e.g., '2024-01-15T10:30:00Z')" }
+	);
+
+/**
+ * Optional ISO 8601 date string validation schema
+ */
+export const optionalIsoDateStringSchema = z
+	.string()
+	.refine(
+		(val) => {
+			// First check format matches ISO 8601
+			if (!ISO_DATE_REGEX.test(val)) return false;
+			// Then verify it's a valid date
+			const date = new Date(val);
+			return !isNaN(date.getTime());
+		},
+		{ message: "Invalid date format. Use ISO 8601 format (e.g., '2024-01-15T10:30:00Z')" }
+	)
+	.optional();
+
+/**
+ * UUID validation schema
+ */
+export const uuidSchema = z
+	.string()
+	.uuid("Invalid UUID format")
+	.or(z.string().min(1, "ID is required"));
+
+/**
+ * Brand ID validation schema
+ */
+export const brandIdSchema = z
+	.string()
+	.min(1, "Brand ID is required");
+
+/**
+ * Tag validation schema
+ * - Non-empty string
+ * - Max 50 characters per tag
+ * - Trimmed and lowercased for consistency
+ */
+export const tagSchema = z
+	.string()
+	.trim()
+	.toLowerCase()
+	.min(1, "Tag cannot be empty")
+	.max(50, "Tag must not exceed 50 characters");
+
+/**
+ * Tags array validation schema
+ * - Array of valid tags
+ * - Max 100 tags per contact
+ */
+export const tagsArraySchema = z
+	.array(tagSchema)
+	.max(100, "Cannot have more than 100 tags")
+	.optional();
+
+// ============================================
+// Custom Field Validation Schemas
+// ============================================
+
+/**
+ * Supported custom field types
+ */
+export const CustomFieldType = {
+	STRING: "string",
+	NUMBER: "number",
+	BOOLEAN: "boolean",
+	DATE: "date",
+	ARRAY: "array",
+	OBJECT: "object",
+} as const;
+
+export type CustomFieldTypeValue = (typeof CustomFieldType)[keyof typeof CustomFieldType];
+
+/**
+ * Custom field definition schema
+ * Defines the structure for a single custom field
+ */
+export const customFieldDefinitionSchema = z.object({
+	type: z.enum(["string", "number", "boolean", "date", "array", "object"]),
+	required: z.boolean().optional().default(false),
+	maxLength: z.number().positive().optional(),
+	minLength: z.number().nonnegative().optional(),
+	min: z.number().optional(),
+	max: z.number().optional(),
+	pattern: z.string().optional(),
+	enum: z.array(z.union([z.string(), z.number()])).optional(),
+});
+
+export type CustomFieldDefinition = z.infer<typeof customFieldDefinitionSchema>;
+
+/**
+ * Custom field value schema
+ * Validates a value based on its field definition
+ */
+export function createCustomFieldValueSchema(definition: CustomFieldDefinition): z.ZodTypeAny {
+	let schema: z.ZodTypeAny;
+
+	switch (definition.type) {
+		case "string":
+			schema = z.string();
+			if (definition.maxLength) {
+				schema = (schema as z.ZodString).max(definition.maxLength);
+			}
+			if (definition.minLength) {
+				schema = (schema as z.ZodString).min(definition.minLength);
+			}
+			if (definition.pattern) {
+				schema = (schema as z.ZodString).regex(new RegExp(definition.pattern));
+			}
+			if (definition.enum) {
+				schema = z.enum(definition.enum as [string, ...string[]]);
+			}
+			break;
+
+		case "number":
+			schema = z.number();
+			if (definition.min !== undefined) {
+				schema = (schema as z.ZodNumber).min(definition.min);
+			}
+			if (definition.max !== undefined) {
+				schema = (schema as z.ZodNumber).max(definition.max);
+			}
+			break;
+
+		case "boolean":
+			schema = z.boolean();
+			break;
+
+		case "date":
+			schema = isoDateStringSchema;
+			break;
+
+		case "array":
+			schema = z.array(z.any());
+			break;
+
+		case "object":
+			schema = z.record(z.any());
+			break;
+
+		default:
+			schema = z.any();
+	}
+
+	if (!definition.required) {
+		schema = schema.optional();
+	}
+
+	return schema;
+}
+
+/**
+ * Contact preferences schema
+ * Validates the preferences Record with type-safe structure
+ *
+ * Known preference fields with validation:
+ * - theme: "light" | "dark" | "system"
+ * - language: BCP 47 locale
+ * - notifications: { email: boolean, sms: boolean, push: boolean }
+ * - communication: { preferredChannel: "email" | "phone" | "sms" }
+ * - Other fields: any valid JSON value
+ */
+export const contactPreferencesSchema = z
+	.record(
+		z.string(),
+		z.union([
+			z.string(),
+			z.number(),
+			z.boolean(),
+			z.array(z.any()),
+			z.record(z.any()),
+			z.null(),
+		])
+	)
+	.optional()
+	.refine(
+		(preferences) => {
+			if (!preferences) return true;
+
+			// Validate known preference fields if present
+			if (preferences.theme && !["light", "dark", "system"].includes(preferences.theme as string)) {
+				return false;
+			}
+
+			if (preferences.language && typeof preferences.language === "string") {
+				const localeResult = localeSchema.safeParse(preferences.language);
+				if (!localeResult.success) return false;
+			}
+
+			return true;
+		},
+		{
+			message: "Invalid preferences structure. Check theme (light/dark/system) and language (BCP 47) values.",
+		}
+	);
+
+/**
+ * Notification preferences sub-schema
+ */
+export const notificationPreferencesSchema = z.object({
+	email: z.boolean().optional().default(true),
+	sms: z.boolean().optional().default(false),
+	push: z.boolean().optional().default(false),
+});
+
+/**
+ * Communication preferences sub-schema
+ */
+export const communicationPreferencesSchema = z.object({
+	preferredChannel: z.enum(["email", "phone", "sms"]).optional().default("email"),
+});
+
+// ============================================
+// Complete Contact Schemas
+// ============================================
+
+/**
+ * Base contact fields schema (shared between create and update)
+ */
+const baseContactFieldsSchema = {
+	brandId: brandIdSchema,
+	email: emailSchema,
+	phone: optionalPhoneSchema,
+	firstName: firstNameSchema,
+	lastName: lastNameSchema,
+	locale: optionalLocaleSchema,
+	gdprConsent: z.boolean({
+		required_error: "GDPR consent is required",
+		invalid_type_error: "GDPR consent must be a boolean",
+	}),
+	gdprConsentDate: optionalIsoDateStringSchema,
+	marketingOptIn: z.boolean().optional(),
+	preferences: contactPreferencesSchema,
+	tags: tagsArraySchema,
+	totalVisits: z.number().int().min(0, "Total visits cannot be negative").optional(),
+	lastVisitDate: optionalIsoDateStringSchema,
+	firstVisitDate: optionalIsoDateStringSchema,
+	legacyId: z.string().max(255, "Legacy ID must not exceed 255 characters").optional(),
+};
+
+/**
+ * Audit fields for creation
+ */
+const createAuditFieldsSchema = {
+	createdAt: optionalIsoDateStringSchema,
+	createdBy: z.string().optional(),
+	updatedAt: optionalIsoDateStringSchema,
+	updatedBy: z.string().optional(),
+};
+
+/**
+ * Audit fields for updates (includes soft delete)
+ */
+const updateAuditFieldsSchema = {
+	updatedAt: optionalIsoDateStringSchema,
+	updatedBy: z.string().optional(),
+	deletedAt: z.string().nullable().optional(),
+	deletedBy: z.string().nullable().optional(),
+};
+
+/**
+ * Create Contact Schema
+ * Full validation for creating a new contact
+ */
+export const createContactSchema = z.object({
+	...baseContactFieldsSchema,
+	...createAuditFieldsSchema,
+});
+
+/**
+ * Update Contact Schema
+ * Partial validation for updating an existing contact
+ * All fields except 'id' are optional
+ */
+export const updateContactSchema = z.object({
+	id: z.string().min(1, "Contact ID is required"),
+	brandId: brandIdSchema.optional(),
+	email: optionalEmailSchema,
+	phone: optionalPhoneSchema,
+	firstName: optionalFirstNameSchema,
+	lastName: optionalLastNameSchema,
+	locale: optionalLocaleSchema,
+	gdprConsent: z.boolean().optional(),
+	gdprConsentDate: optionalIsoDateStringSchema,
+	marketingOptIn: z.boolean().optional(),
+	preferences: contactPreferencesSchema,
+	tags: tagsArraySchema,
+	totalVisits: z.number().int().min(0, "Total visits cannot be negative").optional(),
+	lastVisitDate: optionalIsoDateStringSchema,
+	firstVisitDate: optionalIsoDateStringSchema,
+	legacyId: z.string().max(255, "Legacy ID must not exceed 255 characters").optional(),
+	...updateAuditFieldsSchema,
+});
+
+/**
+ * Merge Contacts Schema
+ * Validation for merging duplicate contacts
+ */
+export const mergeContactsSchema = z.object({
+	primaryId: z.string().min(1, "Primary contact ID is required"),
+	duplicateIds: z
+		.array(z.string().min(1, "Duplicate ID cannot be empty"))
+		.min(1, "At least one duplicate ID is required")
+		.max(50, "Cannot merge more than 50 contacts at once"),
+});
+
+/**
+ * Search/Filter Contact Schema
+ * Validation for contact search and filter operations
+ */
+export const searchContactSchema = z.object({
+	brandId: brandIdSchema.optional(),
+	email: z.string().optional(),
+	phone: z.string().optional(),
+	firstName: z.string().optional(),
+	lastName: z.string().optional(),
+	search: z.string().max(255, "Search query must not exceed 255 characters").optional(),
+	tags: z.array(z.string()).optional(),
+	gdprConsent: z.boolean().optional(),
+	marketingOptIn: z.boolean().optional(),
+	includeDeleted: z.boolean().optional().default(false),
+	limit: z.number().int().min(1).max(250).optional().default(25),
+	nextToken: z.string().optional(),
+});
+
+/**
+ * Bulk Import Contact Schema
+ * Validation for importing contacts in bulk
+ */
+export const bulkImportContactSchema = z.object({
+	contacts: z
+		.array(createContactSchema.omit({ createdAt: true, createdBy: true, updatedAt: true, updatedBy: true }))
+		.min(1, "At least one contact is required")
+		.max(1000, "Cannot import more than 1000 contacts at once"),
+	skipDuplicates: z.boolean().optional().default(true),
+	updateExisting: z.boolean().optional().default(false),
+});
+
+// ============================================
+// Type Exports
+// ============================================
+
+export type CreateContactInput = z.infer<typeof createContactSchema>;
+export type UpdateContactInput = z.infer<typeof updateContactSchema>;
+export type MergeContactsInput = z.infer<typeof mergeContactsSchema>;
+export type SearchContactInput = z.infer<typeof searchContactSchema>;
+export type BulkImportContactInput = z.infer<typeof bulkImportContactSchema>;
+export type ContactPreferences = z.infer<typeof contactPreferencesSchema>;
+export type NotificationPreferences = z.infer<typeof notificationPreferencesSchema>;
+export type CommunicationPreferences = z.infer<typeof communicationPreferencesSchema>;
+
+// ============================================
+// Validation Helper Functions
+// ============================================
+
+/**
+ * Validate email address
+ * @param email - Email string to validate
+ * @returns Validation result with success status and normalized email or error
+ */
+export function validateEmail(email: string): z.SafeParseReturnType<string, string> {
+	return emailSchema.safeParse(email);
+}
+
+/**
+ * Validate phone number
+ * @param phone - Phone string to validate
+ * @returns Validation result with success status and normalized phone or error
+ */
+export function validatePhone(phone: string): z.SafeParseReturnType<string, string> {
+	return phoneSchema.safeParse(phone);
+}
+
+/**
+ * Validate contact name
+ * @param firstName - First name to validate
+ * @param lastName - Last name to validate
+ * @returns Object with validation results for both names
+ */
+export function validateContactName(
+	firstName: string,
+	lastName: string
+): {
+	firstName: z.SafeParseReturnType<string, string>;
+	lastName: z.SafeParseReturnType<string, string>;
+	isValid: boolean;
+} {
+	const firstNameResult = firstNameSchema.safeParse(firstName);
+	const lastNameResult = lastNameSchema.safeParse(lastName);
+
+	return {
+		firstName: firstNameResult,
+		lastName: lastNameResult,
+		isValid: firstNameResult.success && lastNameResult.success,
+	};
+}
+
+/**
+ * Validate create contact input
+ * @param input - Contact input to validate
+ * @returns Validation result with success status and validated data or error
+ */
+export function validateCreateContact(
+	input: unknown
+): z.SafeParseReturnType<unknown, CreateContactInput> {
+	return createContactSchema.safeParse(input);
+}
+
+/**
+ * Validate update contact input
+ * @param input - Contact update input to validate
+ * @returns Validation result with success status and validated data or error
+ */
+export function validateUpdateContact(
+	input: unknown
+): z.SafeParseReturnType<unknown, UpdateContactInput> {
+	return updateContactSchema.safeParse(input);
+}
+
+/**
+ * Format Zod errors into user-friendly message
+ * @param error - Zod error object
+ * @returns Formatted error message string
+ */
+export function formatValidationErrors(error: z.ZodError): string {
+	return error.issues
+		.map((issue) => {
+			const path = issue.path.join(".");
+			return path ? `${path}: ${issue.message}` : issue.message;
+		})
+		.join("; ");
+}
+
+/**
+ * Get validation error details as array
+ * @param error - Zod error object
+ * @returns Array of error details with path and message
+ */
+export function getValidationErrorDetails(
+	error: z.ZodError
+): Array<{ path: string; message: string; code: string }> {
+	return error.issues.map((issue) => ({
+		path: issue.path.join("."),
+		message: issue.message,
+		code: issue.code,
+	}));
+}

package/src/validation/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Validation Module
+ *
+ * Exports all Zod validation schemas and utilities for the data package.
+ *
+ * @module @htlkg/data/validation
+ */
+
+// Contact validation schemas and utilities
+export {
+	// Field-level validators
+	emailSchema,
+	optionalEmailSchema,
+	phoneSchema,
+	optionalPhoneSchema,
+	firstNameSchema,
+	lastNameSchema,
+	optionalFirstNameSchema,
+	optionalLastNameSchema,
+	localeSchema,
+	optionalLocaleSchema,
+	isoDateStringSchema,
+	optionalIsoDateStringSchema,
+	uuidSchema,
+	brandIdSchema,
+	tagSchema,
+	tagsArraySchema,
+	// Custom field schemas
+	CustomFieldType,
+	customFieldDefinitionSchema,
+	createCustomFieldValueSchema,
+	contactPreferencesSchema,
+	notificationPreferencesSchema,
+	communicationPreferencesSchema,
+	// Additional entity schemas (not exported from mutations)
+	searchContactSchema,
+	bulkImportContactSchema,
+	// Validation helper functions
+	validateEmail,
+	validatePhone,
+	validateContactName,
+	validateCreateContact,
+	validateUpdateContact,
+	formatValidationErrors,
+	getValidationErrorDetails,
+	// Types (only types not already exported from mutations)
+	type CustomFieldTypeValue,
+	type CustomFieldDefinition,
+	type SearchContactInput,
+	type BulkImportContactInput,
+	type ContactPreferences,
+	type NotificationPreferences,
+	type CommunicationPreferences,
+} from "./contact.schemas";