@htlkg/data 0.0.23 → 0.0.25

package/src/validation/contact.schemas.test.ts

@@ -0,0 +1,975 @@
+/**
+ * Contact Validation Schema Tests
+ *
+ * Comprehensive tests for all Contact Zod validation schemas,
+ * field validators, and helper functions.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+	// Field-level validators
+	emailSchema,
+	optionalEmailSchema,
+	phoneSchema,
+	optionalPhoneSchema,
+	firstNameSchema,
+	lastNameSchema,
+	optionalFirstNameSchema,
+	localeSchema,
+	optionalLocaleSchema,
+	isoDateStringSchema,
+	optionalIsoDateStringSchema,
+	tagSchema,
+	tagsArraySchema,
+	brandIdSchema,
+	// Custom field schemas
+	contactPreferencesSchema,
+	customFieldDefinitionSchema,
+	createCustomFieldValueSchema,
+	// Complete entity schemas
+	createContactSchema,
+	updateContactSchema,
+	mergeContactsSchema,
+	searchContactSchema,
+	bulkImportContactSchema,
+	// Helper functions
+	validateEmail,
+	validatePhone,
+	validateContactName,
+	validateCreateContact,
+	validateUpdateContact,
+	formatValidationErrors,
+	getValidationErrorDetails,
+} from "./contact.schemas";
+
+// ============================================
+// Email Validation Tests
+// ============================================
+
+describe("Email Validation", () => {
+	describe("emailSchema", () => {
+		it("should accept valid email addresses", () => {
+			const validEmails = [
+				"test@example.com",
+				"user.name@domain.org",
+				"user+tag@subdomain.domain.com",
+				"firstname.lastname@company.co.uk",
+			];
+
+			validEmails.forEach((email) => {
+				const result = emailSchema.safeParse(email);
+				expect(result.success).toBe(true);
+			});
+		});
+
+		it("should transform email to lowercase", () => {
+			const result = emailSchema.safeParse("TEST@EXAMPLE.COM");
+			expect(result.success).toBe(true);
+			if (result.success) {
+				expect(result.data).toBe("test@example.com");
+			}
+		});
+
+		it("should trim whitespace from email", () => {
+			const result = emailSchema.safeParse("  test@example.com  ");
+			expect(result.success).toBe(true);
+			if (result.success) {
+				expect(result.data).toBe("test@example.com");
+			}
+		});
+
+		it("should reject invalid email formats", () => {
+			const invalidEmails = [
+				"invalid",
+				"@example.com",
+				"user@",
+				"user@.com",
+				"user name@example.com",
+				"",
+			];
+
+			invalidEmails.forEach((email) => {
+				const result = emailSchema.safeParse(email);
+				expect(result.success).toBe(false);
+			});
+		});
+
+		it("should reject emails exceeding 254 characters", () => {
+			const longEmail = "a".repeat(250) + "@example.com";
+			const result = emailSchema.safeParse(longEmail);
+			expect(result.success).toBe(false);
+		});
+	});
+
+	describe("optionalEmailSchema", () => {
+		it("should accept undefined", () => {
+			const result = optionalEmailSchema.safeParse(undefined);
+			expect(result.success).toBe(true);
+		});
+
+		it("should validate email when provided", () => {
+			const result = optionalEmailSchema.safeParse("test@example.com");
+			expect(result.success).toBe(true);
+		});
+
+		it("should reject invalid email when provided", () => {
+			const result = optionalEmailSchema.safeParse("invalid-email");
+			expect(result.success).toBe(false);
+		});
+	});
+
+	describe("validateEmail helper", () => {
+		it("should return success for valid email", () => {
+			const result = validateEmail("user@example.com");
+			expect(result.success).toBe(true);
+		});
+
+		it("should return error for invalid email", () => {
+			const result = validateEmail("invalid");
+			expect(result.success).toBe(false);
+		});
+	});
+});
+
+// ============================================
+// Phone Validation Tests
+// ============================================
+
+describe("Phone Validation", () => {
+	describe("phoneSchema", () => {
+		it("should accept valid phone formats", () => {
+			const validPhones = [
+				"+14155552671",
+				"+1 415-555-2671",
+				"(415) 555-2671",
+				"415-555-2671",
+				"4155552671",
+				"+44 20 7946 0958",
+				"+49 30 12345678",
+			];
+
+			validPhones.forEach((phone) => {
+				const result = phoneSchema.safeParse(phone);
+				expect(result.success, `Expected ${phone} to be valid`).toBe(true);
+			});
+		});
+
+		it("should reject phones shorter than 7 characters", () => {
+			const result = phoneSchema.safeParse("12345");
+			expect(result.success).toBe(false);
+		});
+
+		it("should reject phones longer than 20 characters", () => {
+			const result = phoneSchema.safeParse("+1 234 567 890 123 456 789");
+			expect(result.success).toBe(false);
+		});
+
+		it("should reject invalid phone formats", () => {
+			const invalidPhones = ["abc", "phone: 123", "123"];
+
+			invalidPhones.forEach((phone) => {
+				const result = phoneSchema.safeParse(phone);
+				expect(result.success).toBe(false);
+			});
+		});
+
+		it("should trim whitespace", () => {
+			const result = phoneSchema.safeParse("  +14155552671  ");
+			expect(result.success).toBe(true);
+			if (result.success) {
+				expect(result.data).toBe("+14155552671");
+			}
+		});
+	});
+
+	describe("optionalPhoneSchema", () => {
+		it("should accept undefined", () => {
+			const result = optionalPhoneSchema.safeParse(undefined);
+			expect(result.success).toBe(true);
+		});
+
+		it("should accept empty string", () => {
+			const result = optionalPhoneSchema.safeParse("");
+			expect(result.success).toBe(true);
+		});
+
+		it("should validate phone when provided", () => {
+			const result = optionalPhoneSchema.safeParse("+14155552671");
+			expect(result.success).toBe(true);
+		});
+	});
+
+	describe("validatePhone helper", () => {
+		it("should return success for valid phone", () => {
+			const result = validatePhone("+14155552671");
+			expect(result.success).toBe(true);
+		});
+
+		it("should return error for invalid phone", () => {
+			const result = validatePhone("abc");
+			expect(result.success).toBe(false);
+		});
+	});
+});
+
+// ============================================
+// Name Validation Tests
+// ============================================
+
+describe("Name Validation", () => {
+	describe("firstNameSchema", () => {
+		it("should accept valid first names", () => {
+			const validNames = [
+				"John",
+				"María",
+				"Jean-Pierre",
+				"O'Connor",
+				"李",
+				"محمد",
+				"Müller",
+				"Dr. Smith",
+			];
+
+			validNames.forEach((name) => {
+				const result = firstNameSchema.safeParse(name);
+				expect(result.success, `Expected "${name}" to be valid`).toBe(true);
+			});
+		});
+
+		it("should reject empty first name", () => {
+			const result = firstNameSchema.safeParse("");
+			expect(result.success).toBe(false);
+		});
+
+		it("should reject first name exceeding 100 characters", () => {
+			const longName = "A".repeat(101);
+			const result = firstNameSchema.safeParse(longName);
+			expect(result.success).toBe(false);
+		});
+
+		it("should reject names with invalid characters", () => {
+			const invalidNames = ["John123", "Test@Name", "Name!"];
+
+			invalidNames.forEach((name) => {
+				const result = firstNameSchema.safeParse(name);
+				expect(result.success).toBe(false);
+			});
+		});
+
+		it("should trim whitespace", () => {
+			const result = firstNameSchema.safeParse("  John  ");
+			expect(result.success).toBe(true);
+			if (result.success) {
+				expect(result.data).toBe("John");
+			}
+		});
+	});
+
+	describe("lastNameSchema", () => {
+		it("should accept valid last names", () => {
+			const validNames = ["Doe", "García", "van der Berg", "McDonald's"];
+
+			validNames.forEach((name) => {
+				const result = lastNameSchema.safeParse(name);
+				expect(result.success, `Expected "${name}" to be valid`).toBe(true);
+			});
+		});
+
+		it("should reject empty last name", () => {
+			const result = lastNameSchema.safeParse("");
+			expect(result.success).toBe(false);
+		});
+	});
+
+	describe("optionalFirstNameSchema", () => {
+		it("should accept undefined", () => {
+			const result = optionalFirstNameSchema.safeParse(undefined);
+			expect(result.success).toBe(true);
+		});
+
+		it("should reject empty string when provided", () => {
+			const result = optionalFirstNameSchema.safeParse("");
+			expect(result.success).toBe(false);
+		});
+	});
+
+	describe("validateContactName helper", () => {
+		it("should validate both names successfully", () => {
+			const result = validateContactName("John", "Doe");
+			expect(result.isValid).toBe(true);
+			expect(result.firstName.success).toBe(true);
+			expect(result.lastName.success).toBe(true);
+		});
+
+		it("should return false when first name is invalid", () => {
+			const result = validateContactName("", "Doe");
+			expect(result.isValid).toBe(false);
+			expect(result.firstName.success).toBe(false);
+		});
+
+		it("should return false when last name is invalid", () => {
+			const result = validateContactName("John", "");
+			expect(result.isValid).toBe(false);
+			expect(result.lastName.success).toBe(false);
+		});
+	});
+});
+
+// ============================================
+// Locale Validation Tests
+// ============================================
+
+describe("Locale Validation", () => {
+	describe("localeSchema", () => {
+		it("should accept valid BCP 47 locales", () => {
+			const validLocales = ["en", "en-US", "pt-BR", "zh-Hans-CN", "es-419"];
+
+			validLocales.forEach((locale) => {
+				const result = localeSchema.safeParse(locale);
+				expect(result.success, `Expected "${locale}" to be valid`).toBe(true);
+			});
+		});
+
+		it("should reject invalid locale formats", () => {
+			const invalidLocales = ["english", "EN_US", "e", "12-34"];
+
+			invalidLocales.forEach((locale) => {
+				const result = localeSchema.safeParse(locale);
+				expect(result.success).toBe(false);
+			});
+		});
+	});
+
+	describe("optionalLocaleSchema", () => {
+		it("should accept undefined", () => {
+			const result = optionalLocaleSchema.safeParse(undefined);
+			expect(result.success).toBe(true);
+		});
+
+		it("should validate locale when provided", () => {
+			const result = optionalLocaleSchema.safeParse("en-US");
+			expect(result.success).toBe(true);
+		});
+	});
+});
+
+// ============================================
+// Date Validation Tests
+// ============================================
+
+describe("ISO Date String Validation", () => {
+	describe("isoDateStringSchema", () => {
+		it("should accept valid ISO 8601 date strings", () => {
+			const validDates = [
+				"2024-01-15T10:30:00Z",
+				"2024-01-15T10:30:00.000Z",
+				"2024-01-15",
+				"2024-06-01T14:30:00+02:00",
+			];
+
+			validDates.forEach((date) => {
+				const result = isoDateStringSchema.safeParse(date);
+				expect(result.success, `Expected "${date}" to be valid`).toBe(true);
+			});
+		});
+
+		it("should reject invalid date strings", () => {
+			const invalidDates = ["not-a-date", "2024/01/15", "15-01-2024", "invalid", "Jan 15, 2024"];
+
+			invalidDates.forEach((date) => {
+				const result = isoDateStringSchema.safeParse(date);
+				expect(result.success, `Expected "${date}" to be invalid`).toBe(false);
+			});
+		});
+	});
+
+	describe("optionalIsoDateStringSchema", () => {
+		it("should accept undefined", () => {
+			const result = optionalIsoDateStringSchema.safeParse(undefined);
+			expect(result.success).toBe(true);
+		});
+
+		it("should validate date when provided", () => {
+			const result = optionalIsoDateStringSchema.safeParse("2024-01-15T10:30:00Z");
+			expect(result.success).toBe(true);
+		});
+	});
+});
+
+// ============================================
+// Tag Validation Tests
+// ============================================
+
+describe("Tag Validation", () => {
+	describe("tagSchema", () => {
+		it("should accept valid tags", () => {
+			const result = tagSchema.safeParse("vip");
+			expect(result.success).toBe(true);
+		});
+
+		it("should transform to lowercase and trim", () => {
+			const result = tagSchema.safeParse("  VIP  ");
+			expect(result.success).toBe(true);
+			if (result.success) {
+				expect(result.data).toBe("vip");
+			}
+		});
+
+		it("should reject empty tags", () => {
+			const result = tagSchema.safeParse("");
+			expect(result.success).toBe(false);
+		});
+
+		it("should reject tags exceeding 50 characters", () => {
+			const longTag = "a".repeat(51);
+			const result = tagSchema.safeParse(longTag);
+			expect(result.success).toBe(false);
+		});
+	});
+
+	describe("tagsArraySchema", () => {
+		it("should accept valid tags array", () => {
+			const result = tagsArraySchema.safeParse(["vip", "returning", "newsletter"]);
+			expect(result.success).toBe(true);
+		});
+
+		it("should accept undefined", () => {
+			const result = tagsArraySchema.safeParse(undefined);
+			expect(result.success).toBe(true);
+		});
+
+		it("should reject arrays with more than 100 tags", () => {
+			const tooManyTags = Array(101).fill("tag");
+			const result = tagsArraySchema.safeParse(tooManyTags);
+			expect(result.success).toBe(false);
+		});
+
+		it("should reject arrays with empty tags", () => {
+			const result = tagsArraySchema.safeParse(["valid", ""]);
+			expect(result.success).toBe(false);
+		});
+	});
+});
+
+// ============================================
+// Brand ID Validation Tests
+// ============================================
+
+describe("Brand ID Validation", () => {
+	describe("brandIdSchema", () => {
+		it("should accept non-empty brand ID", () => {
+			const result = brandIdSchema.safeParse("brand-123");
+			expect(result.success).toBe(true);
+		});
+
+		it("should reject empty brand ID", () => {
+			const result = brandIdSchema.safeParse("");
+			expect(result.success).toBe(false);
+		});
+	});
+});
+
+// ============================================
+// Custom Field Validation Tests
+// ============================================
+
+describe("Custom Field Validation", () => {
+	describe("customFieldDefinitionSchema", () => {
+		it("should accept valid string field definition", () => {
+			const result = customFieldDefinitionSchema.safeParse({
+				type: "string",
+				maxLength: 100,
+				required: true,
+			});
+			expect(result.success).toBe(true);
+		});
+
+		it("should accept valid number field definition", () => {
+			const result = customFieldDefinitionSchema.safeParse({
+				type: "number",
+				min: 0,
+				max: 100,
+			});
+			expect(result.success).toBe(true);
+		});
+
+		it("should reject invalid field type", () => {
+			const result = customFieldDefinitionSchema.safeParse({
+				type: "invalid",
+			});
+			expect(result.success).toBe(false);
+		});
+	});
+
+	describe("createCustomFieldValueSchema", () => {
+		it("should create string schema with constraints", () => {
+			const schema = createCustomFieldValueSchema({
+				type: "string",
+				maxLength: 10,
+				required: true,
+			});
+
+			expect(schema.safeParse("short").success).toBe(true);
+			expect(schema.safeParse("this is too long").success).toBe(false);
+		});
+
+		it("should create number schema with constraints", () => {
+			const schema = createCustomFieldValueSchema({
+				type: "number",
+				min: 0,
+				max: 100,
+				required: true,
+			});
+
+			expect(schema.safeParse(50).success).toBe(true);
+			expect(schema.safeParse(150).success).toBe(false);
+			expect(schema.safeParse(-10).success).toBe(false);
+		});
+
+		it("should create boolean schema", () => {
+			const schema = createCustomFieldValueSchema({
+				type: "boolean",
+				required: true,
+			});
+
+			expect(schema.safeParse(true).success).toBe(true);
+			expect(schema.safeParse(false).success).toBe(true);
+			expect(schema.safeParse("true").success).toBe(false);
+		});
+
+		it("should create date schema", () => {
+			const schema = createCustomFieldValueSchema({
+				type: "date",
+				required: true,
+			});
+
+			expect(schema.safeParse("2024-01-15T10:30:00Z").success).toBe(true);
+			expect(schema.safeParse("invalid-date").success).toBe(false);
+		});
+	});
+
+	describe("contactPreferencesSchema", () => {
+		it("should accept valid preferences", () => {
+			const result = contactPreferencesSchema.safeParse({
+				theme: "dark",
+				language: "en-US",
+				notifications: { email: true, sms: false },
+			});
+			expect(result.success).toBe(true);
+		});
+
+		it("should accept undefined", () => {
+			const result = contactPreferencesSchema.safeParse(undefined);
+			expect(result.success).toBe(true);
+		});
+
+		it("should reject invalid theme value", () => {
+			const result = contactPreferencesSchema.safeParse({
+				theme: "invalid-theme",
+			});
+			expect(result.success).toBe(false);
+		});
+
+		it("should reject invalid language locale", () => {
+			const result = contactPreferencesSchema.safeParse({
+				language: "invalid-locale",
+			});
+			expect(result.success).toBe(false);
+		});
+
+		it("should accept custom preferences", () => {
+			const result = contactPreferencesSchema.safeParse({
+				customField: "value",
+				nestedObject: { key: "value" },
+				arrayField: [1, 2, 3],
+			});
+			expect(result.success).toBe(true);
+		});
+	});
+});
+
+// ============================================
+// Create Contact Schema Tests
+// ============================================
+
+describe("Create Contact Schema", () => {
+	const validInput = {
+		brandId: "brand-123",
+		email: "john.doe@example.com",
+		firstName: "John",
+		lastName: "Doe",
+		gdprConsent: true,
+	};
+
+	it("should accept valid minimal input", () => {
+		const result = createContactSchema.safeParse(validInput);
+		expect(result.success).toBe(true);
+	});
+
+	it("should accept valid input with all optional fields", () => {
+		const fullInput = {
+			...validInput,
+			phone: "+14155552671",
+			locale: "en-US",
+			gdprConsentDate: "2024-01-15T10:00:00Z",
+			marketingOptIn: true,
+			preferences: { theme: "dark" },
+			tags: ["vip", "returning"],
+			totalVisits: 5,
+			lastVisitDate: "2024-06-01T14:00:00Z",
+			firstVisitDate: "2023-01-15T10:00:00Z",
+			legacyId: "legacy-123",
+			createdAt: "2024-01-01T00:00:00Z",
+			createdBy: "admin@example.com",
+		};
+
+		const result = createContactSchema.safeParse(fullInput);
+		expect(result.success).toBe(true);
+	});
+
+	it("should reject missing required fields", () => {
+		const missingFields = {
+			email: "test@example.com",
+		};
+
+		const result = createContactSchema.safeParse(missingFields);
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject invalid email", () => {
+		const result = createContactSchema.safeParse({
+			...validInput,
+			email: "invalid-email",
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject invalid phone format", () => {
+		const result = createContactSchema.safeParse({
+			...validInput,
+			phone: "abc",
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject negative totalVisits", () => {
+		const result = createContactSchema.safeParse({
+			...validInput,
+			totalVisits: -1,
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should transform email to lowercase", () => {
+		const result = createContactSchema.safeParse({
+			...validInput,
+			email: "JOHN.DOE@EXAMPLE.COM",
+		});
+		expect(result.success).toBe(true);
+		if (result.success) {
+			expect(result.data.email).toBe("john.doe@example.com");
+		}
+	});
+
+	describe("validateCreateContact helper", () => {
+		it("should validate create input", () => {
+			const result = validateCreateContact(validInput);
+			expect(result.success).toBe(true);
+		});
+
+		it("should return errors for invalid input", () => {
+			const result = validateCreateContact({ email: "invalid" });
+			expect(result.success).toBe(false);
+		});
+	});
+});
+
+// ============================================
+// Update Contact Schema Tests
+// ============================================
+
+describe("Update Contact Schema", () => {
+	it("should accept valid update with id only", () => {
+		const result = updateContactSchema.safeParse({
+			id: "contact-123",
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it("should accept partial updates", () => {
+		const result = updateContactSchema.safeParse({
+			id: "contact-123",
+			firstName: "Jane",
+			marketingOptIn: true,
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it("should reject missing id", () => {
+		const result = updateContactSchema.safeParse({
+			firstName: "Jane",
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject empty id", () => {
+		const result = updateContactSchema.safeParse({
+			id: "",
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should accept soft delete fields", () => {
+		const result = updateContactSchema.safeParse({
+			id: "contact-123",
+			deletedAt: "2024-01-15T10:00:00Z",
+			deletedBy: "admin@example.com",
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it("should accept null for soft delete fields (restore)", () => {
+		const result = updateContactSchema.safeParse({
+			id: "contact-123",
+			deletedAt: null,
+			deletedBy: null,
+		});
+		expect(result.success).toBe(true);
+	});
+
+	describe("validateUpdateContact helper", () => {
+		it("should validate update input", () => {
+			const result = validateUpdateContact({ id: "contact-123", firstName: "Jane" });
+			expect(result.success).toBe(true);
+		});
+
+		it("should return errors for invalid input", () => {
+			const result = validateUpdateContact({ id: "" });
+			expect(result.success).toBe(false);
+		});
+	});
+});
+
+// ============================================
+// Merge Contacts Schema Tests
+// ============================================
+
+describe("Merge Contacts Schema", () => {
+	it("should accept valid merge input", () => {
+		const result = mergeContactsSchema.safeParse({
+			primaryId: "contact-primary",
+			duplicateIds: ["contact-dup-1", "contact-dup-2"],
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it("should reject missing primaryId", () => {
+		const result = mergeContactsSchema.safeParse({
+			duplicateIds: ["contact-dup-1"],
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject empty primaryId", () => {
+		const result = mergeContactsSchema.safeParse({
+			primaryId: "",
+			duplicateIds: ["contact-dup-1"],
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject empty duplicateIds array", () => {
+		const result = mergeContactsSchema.safeParse({
+			primaryId: "contact-primary",
+			duplicateIds: [],
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject duplicateIds with empty strings", () => {
+		const result = mergeContactsSchema.safeParse({
+			primaryId: "contact-primary",
+			duplicateIds: ["contact-dup-1", ""],
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject more than 50 duplicate contacts", () => {
+		const tooManyDuplicates = Array(51)
+			.fill(null)
+			.map((_, i) => `contact-dup-${i}`);
+
+		const result = mergeContactsSchema.safeParse({
+			primaryId: "contact-primary",
+			duplicateIds: tooManyDuplicates,
+		});
+		expect(result.success).toBe(false);
+	});
+});
+
+// ============================================
+// Search Contact Schema Tests
+// ============================================
+
+describe("Search Contact Schema", () => {
+	it("should accept empty search (all contacts)", () => {
+		const result = searchContactSchema.safeParse({});
+		expect(result.success).toBe(true);
+	});
+
+	it("should accept valid search parameters", () => {
+		const result = searchContactSchema.safeParse({
+			brandId: "brand-123",
+			search: "john",
+			tags: ["vip"],
+			gdprConsent: true,
+			limit: 50,
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it("should reject search query exceeding 255 characters", () => {
+		const result = searchContactSchema.safeParse({
+			search: "a".repeat(256),
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject limit below 1", () => {
+		const result = searchContactSchema.safeParse({
+			limit: 0,
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject limit above 250", () => {
+		const result = searchContactSchema.safeParse({
+			limit: 251,
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should apply default values", () => {
+		const result = searchContactSchema.safeParse({});
+		expect(result.success).toBe(true);
+		if (result.success) {
+			expect(result.data.includeDeleted).toBe(false);
+			expect(result.data.limit).toBe(25);
+		}
+	});
+});
+
+// ============================================
+// Bulk Import Schema Tests
+// ============================================
+
+describe("Bulk Import Contact Schema", () => {
+	const validContact = {
+		brandId: "brand-123",
+		email: "test@example.com",
+		firstName: "John",
+		lastName: "Doe",
+		gdprConsent: true,
+	};
+
+	it("should accept valid bulk import", () => {
+		const result = bulkImportContactSchema.safeParse({
+			contacts: [validContact, { ...validContact, email: "jane@example.com" }],
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it("should reject empty contacts array", () => {
+		const result = bulkImportContactSchema.safeParse({
+			contacts: [],
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should reject more than 1000 contacts", () => {
+		const tooManyContacts = Array(1001)
+			.fill(null)
+			.map((_, i) => ({
+				...validContact,
+				email: `user${i}@example.com`,
+			}));
+
+		const result = bulkImportContactSchema.safeParse({
+			contacts: tooManyContacts,
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it("should apply default values", () => {
+		const result = bulkImportContactSchema.safeParse({
+			contacts: [validContact],
+		});
+		expect(result.success).toBe(true);
+		if (result.success) {
+			expect(result.data.skipDuplicates).toBe(true);
+			expect(result.data.updateExisting).toBe(false);
+		}
+	});
+
+	it("should validate individual contacts", () => {
+		const result = bulkImportContactSchema.safeParse({
+			contacts: [{ ...validContact, email: "invalid-email" }],
+		});
+		expect(result.success).toBe(false);
+	});
+});
+
+// ============================================
+// Error Formatting Tests
+// ============================================
+
+describe("Error Formatting Helpers", () => {
+	describe("formatValidationErrors", () => {
+		it("should format errors into readable string", () => {
+			const result = createContactSchema.safeParse({
+				email: "invalid",
+			});
+
+			if (!result.success) {
+				const formatted = formatValidationErrors(result.error);
+				expect(formatted).toContain("email");
+				expect(formatted).toContain("Invalid email");
+			}
+		});
+
+		it("should handle nested path errors", () => {
+			const result = createContactSchema.safeParse({
+				brandId: "brand-123",
+				email: "test@example.com",
+				firstName: "John",
+				lastName: "Doe",
+				gdprConsent: true,
+				preferences: {
+					theme: "invalid-theme",
+				},
+			});
+
+			if (!result.success) {
+				const formatted = formatValidationErrors(result.error);
+				expect(typeof formatted).toBe("string");
+			}
+		});
+	});
+
+	describe("getValidationErrorDetails", () => {
+		it("should return array of error details", () => {
+			const result = createContactSchema.safeParse({
+				email: "invalid",
+			});
+
+			if (!result.success) {
+				const details = getValidationErrorDetails(result.error);
+				expect(Array.isArray(details)).toBe(true);
+				expect(details.length).toBeGreaterThan(0);
+				expect(details[0]).toHaveProperty("path");
+				expect(details[0]).toHaveProperty("message");
+				expect(details[0]).toHaveProperty("code");
+			}
+		});
+	});
+});