@htlkg/data 0.0.20 → 0.0.21

package/src/mutations/contacts.ts

@@ -0,0 +1,554 @@
+/**
+ * Contact Mutation Functions
+ *
+ * Provides type-safe mutation functions for creating, updating, and deleting contacts.
+ * Includes Zod validation for input data before mutations.
+ */
+
+import { z } from "zod";
+import type { Contact } from "@htlkg/core/types";
+import {
+	checkRestoreEligibility,
+	DEFAULT_SOFT_DELETE_RETENTION_DAYS,
+} from "../queries/systemSettings";
+import { getContact } from "../queries/contacts";
+import type { CreateAuditFields, UpdateWithSoftDeleteFields } from "./common";
+
+// ============================================
+//  Added Zod Validation Schemas
+// ============================================
+
+/**
+ * Zod schema for creating a contact 
+ */
+export const createContactSchema = z.object({
+	brandId: z.string().min(1, "Brand ID is required"),
+	email: z.string().email("Invalid email address"),
+	phone: z.string().optional(),
+	firstName: z.string().min(1, "First name is required"),
+	lastName: z.string().min(1, "Last name is required"),
+	locale: z.string().optional(),
+	gdprConsent: z.boolean(),
+	gdprConsentDate: z.string().optional(),
+	marketingOptIn: z.boolean().optional(),
+	preferences: z.record(z.any()).optional(),
+	tags: z.array(z.string()).optional(),
+	totalVisits: z.number().int().min(0).optional(),
+	lastVisitDate: z.string().optional(),
+	firstVisitDate: z.string().optional(),
+	legacyId: z.string().optional(),
+	// Audit fields
+	createdAt: z.string().optional(),
+	createdBy: z.string().optional(),
+	updatedAt: z.string().optional(),
+	updatedBy: z.string().optional(),
+});
+
+/**
+ * Zod schema for updating a contact
+ */
+export const updateContactSchema = z.object({
+	id: z.string().min(1, "Contact ID is required"),
+	brandId: z.string().min(1).optional(),
+	email: z.string().email("Invalid email address").optional(),
+	phone: z.string().optional(),
+	firstName: z.string().min(1).optional(),
+	lastName: z.string().min(1).optional(),
+	locale: z.string().optional(),
+	gdprConsent: z.boolean().optional(),
+	gdprConsentDate: z.string().optional(),
+	marketingOptIn: z.boolean().optional(),
+	preferences: z.record(z.any()).optional(),
+	tags: z.array(z.string()).optional(),
+	totalVisits: z.number().int().min(0).optional(),
+	lastVisitDate: z.string().optional(),
+	firstVisitDate: z.string().optional(),
+	legacyId: z.string().optional(),
+	// Audit fields
+	updatedAt: z.string().optional(),
+	updatedBy: z.string().optional(),
+	deletedAt: z.string().nullable().optional(),
+	deletedBy: z.string().nullable().optional(),
+});
+
+/**
+ * Zod schema for merging contacts
+ */
+export const mergeContactsSchema = z.object({
+	primaryId: z.string().min(1, "Primary contact ID is required"),
+	duplicateIds: z.array(z.string().min(1)).min(1, "At least one duplicate ID is required"),
+});
+
+// ============================================
+// Validation Error Class
+// ============================================
+
+/**
+ * Validation error class for contact operations
+ */
+export class ContactValidationError extends Error {
+	public readonly issues: z.ZodIssue[];
+
+	constructor(message: string, issues: z.ZodIssue[] = []) {
+		super(message);
+		this.name = "ContactValidationError";
+		this.issues = issues;
+	}
+}
+
+// ============================================
+// Input Types
+// ============================================
+
+/**
+ * Input type for creating a contact
+ */
+export interface CreateContactInput extends CreateAuditFields {
+	brandId: string;
+	email: string;
+	phone?: string;
+	firstName: string;
+	lastName: string;
+	locale?: string;
+	gdprConsent: boolean;
+	gdprConsentDate?: string;
+	marketingOptIn?: boolean;
+	preferences?: Record<string, any>;
+	tags?: string[];
+	totalVisits?: number;
+	lastVisitDate?: string;
+	firstVisitDate?: string;
+	legacyId?: string;
+}
+
+/**
+ * Input type for updating a contact
+ */
+export interface UpdateContactInput extends UpdateWithSoftDeleteFields {
+	id: string;
+	brandId?: string;
+	email?: string;
+	phone?: string;
+	firstName?: string;
+	lastName?: string;
+	locale?: string;
+	gdprConsent?: boolean;
+	gdprConsentDate?: string;
+	marketingOptIn?: boolean;
+	preferences?: Record<string, any>;
+	tags?: string[];
+	totalVisits?: number;
+	lastVisitDate?: string;
+	firstVisitDate?: string;
+	legacyId?: string;
+}
+
+/**
+ * Input type for merging contacts
+ */
+export interface MergeContactsInput {
+	primaryId: string;
+	duplicateIds: string[];
+}
+
+/**
+ * Result type for merge operation
+ */
+export interface MergeContactsResult {
+	success: boolean;
+	mergedContact?: Contact;
+	deletedIds?: string[];
+	error?: string;
+}
+
+// ============================================
+// Mutation Functions
+// ============================================
+
+/**
+ * Create a new contact with Zod validation
+ *
+ * @throws {ContactValidationError} if input validation fails
+ *
+ * @example
+ * ```typescript
+ * import { createContact } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const contact = await createContact(client, {
+ *   brandId: 'brand-123',
+ *   email: 'guest@example.com',
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ *   gdprConsent: true,
+ *   gdprConsentDate: new Date().toISOString()
+ * });
+ * ```
+ */
+export async function createContact<TClient = any>(
+	client: TClient,
+	input: CreateContactInput,
+): Promise<Contact | null> {
+	try {
+		// Validate input with Zod
+		const validationResult = createContactSchema.safeParse(input);
+
+		if (!validationResult.success) {
+			const errorMessage = validationResult.error.issues
+				.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+				.join(", ");
+			throw new ContactValidationError(
+				`Validation failed: ${errorMessage}`,
+				validationResult.error.issues
+			);
+		}
+
+		const { data, errors } = await (client as any).models.Contact.create(input);
+
+		if (errors) {
+			console.error("[createContact] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data as Contact;
+	} catch (error) {
+		if (error instanceof ContactValidationError) {
+			console.error("[createContact] Validation error:", error.message);
+			throw error;
+		}
+		console.error("[createContact] Error creating contact:", error);
+		throw error;
+	}
+}
+
+/**
+ * Update an existing contact with Zod validation
+ *
+ * @throws {ContactValidationError} if input validation fails
+ *
+ * @example
+ * ```typescript
+ * import { updateContact } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const contact = await updateContact(client, {
+ *   id: 'contact-123',
+ *   firstName: 'Jane',
+ *   marketingOptIn: true
+ * });
+ * ```
+ */
+export async function updateContact<TClient = any>(
+	client: TClient,
+	input: UpdateContactInput,
+): Promise<Contact | null> {
+	try {
+		// Validate input with Zod
+		const validationResult = updateContactSchema.safeParse(input);
+
+		if (!validationResult.success) {
+			const errorMessage = validationResult.error.issues
+				.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+				.join(", ");
+			throw new ContactValidationError(
+				`Validation failed: ${errorMessage}`,
+				validationResult.error.issues
+			);
+		}
+
+		const { data, errors } = await (client as any).models.Contact.update(input);
+
+		if (errors) {
+			console.error("[updateContact] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data as Contact;
+	} catch (error) {
+		if (error instanceof ContactValidationError) {
+			console.error("[updateContact] Validation error:", error.message);
+			throw error;
+		}
+		console.error("[updateContact] Error updating contact:", error);
+		throw error;
+	}
+}
+
+/**
+ * Soft delete a contact (sets deletedAt/deletedBy instead of removing)
+ *
+ * @example
+ * ```typescript
+ * import { softDeleteContact } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * await softDeleteContact(client, 'contact-123', 'admin@example.com');
+ * ```
+ */
+export async function softDeleteContact<TClient = any>(
+	client: TClient,
+	id: string,
+	deletedBy: string,
+): Promise<boolean> {
+	try {
+		const { errors } = await (client as any).models.Contact.update({
+			id,
+			deletedAt: new Date().toISOString(),
+			deletedBy,
+		});
+
+		if (errors) {
+			console.error("[softDeleteContact] GraphQL errors:", errors);
+			return false;
+		}
+
+		return true;
+	} catch (error) {
+		console.error("[softDeleteContact] Error soft-deleting contact:", error);
+		throw error;
+	}
+}
+
+/**
+ * Restore a soft-deleted contact
+ * Checks retention period before allowing restoration
+ *
+ * @example
+ * ```typescript
+ * import { restoreContact } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * await restoreContact(client, 'contact-123');
+ * // Or with custom retention days:
+ * await restoreContact(client, 'contact-123', 60);
+ * ```
+ */
+export async function restoreContact<TClient = any>(
+	client: TClient,
+	id: string,
+	retentionDays: number = DEFAULT_SOFT_DELETE_RETENTION_DAYS,
+): Promise<{ success: boolean; error?: string }> {
+	try {
+		// First, get the contact to check its deletedAt timestamp
+		const contact = await getContact(client, id);
+
+		if (!contact) {
+			console.error("[restoreContact] Contact not found");
+			return { success: false, error: "Contact not found" };
+		}
+
+		// Check if restoration is allowed based on retention period
+		const eligibility = checkRestoreEligibility(
+			(contact as any).deletedAt,
+			retentionDays
+		);
+
+		if (!eligibility.canRestore) {
+			const errorMsg = `Cannot restore contact. Retention period of ${retentionDays} days has expired. Item was deleted ${eligibility.daysExpired} days ago.`;
+			console.error("[restoreContact]", errorMsg);
+			return { success: false, error: errorMsg };
+		}
+
+		const { errors } = await (client as any).models.Contact.update({
+			id,
+			deletedAt: null,
+			deletedBy: null,
+		});
+
+		if (errors) {
+			console.error("[restoreContact] GraphQL errors:", errors);
+			return { success: false, error: "Failed to restore contact" };
+		}
+
+		return { success: true };
+	} catch (error) {
+		console.error("[restoreContact] Error restoring contact:", error);
+		throw error;
+	}
+}
+
+/**
+ * Hard delete a contact (permanently removes from database)
+ * Use with caution - prefer softDeleteContact for recoverable deletion
+ *
+ * @example
+ * ```typescript
+ * import { deleteContact } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * await deleteContact(client, 'contact-123');
+ * ```
+ */
+export async function deleteContact<TClient = any>(
+	client: TClient,
+	id: string,
+): Promise<boolean> {
+	try {
+		const { errors } = await (client as any).models.Contact.delete({ id });
+
+		if (errors) {
+			console.error("[deleteContact] GraphQL errors:", errors);
+			return false;
+		}
+
+		return true;
+	} catch (error) {
+		console.error("[deleteContact] Error deleting contact:", error);
+		throw error;
+	}
+}
+
+/**
+ * Merge duplicate contacts into a primary contact
+ *
+ * This function:
+ * 1. Validates all contact IDs exist
+ * 2. Aggregates data from duplicates into the primary contact
+ * 3. Soft deletes the duplicate contacts
+ * 4. Returns the updated primary contact
+ *
+ * Merge strategy:
+ * - totalVisits: Sum of all contacts
+ * - firstVisitDate: Earliest date across all contacts
+ * - lastVisitDate: Latest date across all contacts
+ * - tags: Merged unique tags from all contacts
+ * - preferences: Primary contact preferences take precedence
+ * - Other fields: Primary contact values are preserved
+ *
+ * @throws {ContactValidationError} if input validation fails
+ *
+ * @example
+ * ```typescript
+ * import { mergeContacts } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const result = await mergeContacts(client, {
+ *   primaryId: 'contact-primary',
+ *   duplicateIds: ['contact-dup-1', 'contact-dup-2']
+ * }, 'admin@example.com');
+ * ```
+ */
+export async function mergeContacts<TClient = any>(
+	client: TClient,
+	input: MergeContactsInput,
+	mergedBy: string,
+): Promise<MergeContactsResult> {
+	try {
+		// Validate input with Zod
+		const validationResult = mergeContactsSchema.safeParse(input);
+
+		if (!validationResult.success) {
+			const errorMessage = validationResult.error.issues
+				.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+				.join(", ");
+			throw new ContactValidationError(
+				`Validation failed: ${errorMessage}`,
+				validationResult.error.issues
+			);
+		}
+
+		const { primaryId, duplicateIds } = input;
+
+		// Fetch primary contact
+		const primaryContact = await getContact(client, primaryId);
+		if (!primaryContact) {
+			return {
+				success: false,
+				error: `Primary contact not found: ${primaryId}`,
+			};
+		}
+
+		// Fetch all duplicate contacts
+		const duplicateContacts: Contact[] = [];
+		for (const duplicateId of duplicateIds) {
+			const duplicate = await getContact(client, duplicateId);
+			if (!duplicate) {
+				return {
+					success: false,
+					error: `Duplicate contact not found: ${duplicateId}`,
+				};
+			}
+			duplicateContacts.push(duplicate);
+		}
+
+		// Aggregate data from duplicates
+		let totalVisits = primaryContact.totalVisits || 0;
+		let firstVisitDate = primaryContact.firstVisitDate;
+		let lastVisitDate = primaryContact.lastVisitDate;
+		const allTags = new Set<string>(primaryContact.tags || []);
+
+		for (const duplicate of duplicateContacts) {
+			// Sum total visits
+			totalVisits += duplicate.totalVisits || 0;
+
+			// Find earliest first visit date
+			if (duplicate.firstVisitDate) {
+				if (!firstVisitDate || duplicate.firstVisitDate < firstVisitDate) {
+					firstVisitDate = duplicate.firstVisitDate;
+				}
+			}
+
+			// Find latest last visit date
+			if (duplicate.lastVisitDate) {
+				if (!lastVisitDate || duplicate.lastVisitDate > lastVisitDate) {
+					lastVisitDate = duplicate.lastVisitDate;
+				}
+			}
+
+			// Merge tags
+			if (duplicate.tags) {
+				duplicate.tags.forEach((tag) => allTags.add(tag));
+			}
+		}
+
+		// Update primary contact with aggregated data
+		const updateInput: UpdateContactInput = {
+			id: primaryId,
+			totalVisits,
+			firstVisitDate,
+			lastVisitDate,
+			tags: Array.from(allTags),
+			updatedAt: new Date().toISOString(),
+			updatedBy: mergedBy,
+		};
+
+		const updatedPrimary = await updateContact(client, updateInput);
+
+		if (!updatedPrimary) {
+			return {
+				success: false,
+				error: "Failed to update primary contact with merged data",
+			};
+		}
+
+		// Soft delete all duplicate contacts
+		const deletedIds: string[] = [];
+		for (const duplicateId of duplicateIds) {
+			const deleted = await softDeleteContact(client, duplicateId, mergedBy);
+			if (deleted) {
+				deletedIds.push(duplicateId);
+			} else {
+				console.error(`[mergeContacts] Failed to soft-delete duplicate: ${duplicateId}`);
+			}
+		}
+
+		return {
+			success: true,
+			mergedContact: updatedPrimary,
+			deletedIds,
+		};
+	} catch (error) {
+		if (error instanceof ContactValidationError) {
+			console.error("[mergeContacts] Validation error:", error.message);
+			throw error;
+		}
+		console.error("[mergeContacts] Error merging contacts:", error);
+		throw error;
+	}
+}

package/src/mutations/index.ts

@@ -75,3 +75,21 @@ export {
 	type UpdateReservationInput,
 	type ReservationStatus,
 } from "./reservations";
+
+// Contact mutations
+export {
+	createContact,
+	updateContact,
+	deleteContact,
+	softDeleteContact,
+	restoreContact,
+	mergeContacts,
+	ContactValidationError,
+	createContactSchema,
+	updateContactSchema,
+	mergeContactsSchema,
+	type CreateContactInput,
+	type UpdateContactInput,
+	type MergeContactsInput,
+	type MergeContactsResult,
+} from "./contacts";