@htlkg/data 0.0.19 → 0.0.21

package/src/mutations/reservations.ts

@@ -0,0 +1,452 @@
+/**
+ * Reservation Mutation Functions
+ *
+ * Provides type-safe mutation functions for creating, updating, and deleting reservations.
+ * Includes date validation and status transition rules.
+ */
+
+import {
+	checkRestoreEligibility,
+	DEFAULT_SOFT_DELETE_RETENTION_DAYS,
+} from "../queries/systemSettings";
+import type { CreateAuditFields, UpdateWithSoftDeleteFields } from "./common";
+
+/**
+ * Reservation status type
+ */
+export type ReservationStatus = "confirmed" | "checked_in" | "checked_out" | "cancelled" | "no_show";
+
+/**
+ * Valid status transitions for reservations
+ * Maps current status -> allowed next statuses
+ */
+const STATUS_TRANSITIONS: Record<ReservationStatus, ReservationStatus[]> = {
+	confirmed: ["checked_in", "cancelled", "no_show"],
+	checked_in: ["checked_out", "cancelled"],
+	checked_out: [], // Terminal state - no transitions allowed
+	cancelled: [], // Terminal state - no transitions allowed
+	no_show: [], // Terminal state - no transitions allowed
+};
+
+/**
+ * Validation error class for reservation operations
+ */
+export class ReservationValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ReservationValidationError";
+	}
+}
+
+/**
+ * Validate check-in and check-out dates
+ * @throws {ReservationValidationError} if dates are invalid
+ */
+function validateDates(checkIn: string, checkOut: string): void {
+	const checkInDate = new Date(checkIn);
+	const checkOutDate = new Date(checkOut);
+
+	// Check if dates are valid
+	if (isNaN(checkInDate.getTime())) {
+		throw new ReservationValidationError("Invalid check-in date");
+	}
+
+	if (isNaN(checkOutDate.getTime())) {
+		throw new ReservationValidationError("Invalid check-out date");
+	}
+
+	// Check-out must be after check-in
+	if (checkOutDate <= checkInDate) {
+		throw new ReservationValidationError(
+			"Check-out date must be after check-in date"
+		);
+	}
+
+	// Calculate minimum stay (at least a few hours)
+	const minStayHours = 4;
+	const stayDuration = checkOutDate.getTime() - checkInDate.getTime();
+	const hoursDiff = stayDuration / (1000 * 60 * 60);
+
+	if (hoursDiff < minStayHours) {
+		throw new ReservationValidationError(
+			`Minimum stay is ${minStayHours} hours`
+		);
+	}
+}
+
+/**
+ * Validate status transition
+ * @throws {ReservationValidationError} if transition is not allowed
+ */
+function validateStatusTransition(
+	currentStatus: ReservationStatus,
+	newStatus: ReservationStatus
+): void {
+	const allowedTransitions = STATUS_TRANSITIONS[currentStatus];
+
+	if (!allowedTransitions.includes(newStatus)) {
+		throw new ReservationValidationError(
+			`Invalid status transition from '${currentStatus}' to '${newStatus}'. ` +
+			`Allowed transitions: ${allowedTransitions.length > 0 ? allowedTransitions.join(", ") : "none (terminal state)"}`
+		);
+	}
+}
+
+/**
+ * Input type for creating a reservation
+ */
+export interface CreateReservationInput extends CreateAuditFields {
+	brandId: string;
+	visitId: string;
+	confirmationCode: string;
+	checkIn: string;
+	checkOut: string;
+	status?: "confirmed" | "checked_in" | "checked_out" | "cancelled" | "no_show";
+	source?: string;
+	channel?: string;
+	roomType?: string;
+	room?: string;
+	totalAmount?: number;
+	currency?: string;
+	nights?: number;
+}
+
+/**
+ * Input type for updating a reservation
+ */
+export interface UpdateReservationInput extends UpdateWithSoftDeleteFields {
+	id: string;
+	brandId?: string;
+	visitId?: string;
+	confirmationCode?: string;
+	checkIn?: string;
+	checkOut?: string;
+	status?: "confirmed" | "checked_in" | "checked_out" | "cancelled" | "no_show";
+	source?: string;
+	channel?: string;
+	roomType?: string;
+	room?: string;
+	totalAmount?: number;
+	currency?: string;
+	nights?: number;
+}
+
+/**
+ * Create a new reservation with date validation
+ *
+ * @throws {ReservationValidationError} if dates are invalid
+ *
+ * @example
+ * ```typescript
+ * import { createReservation } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const reservation = await createReservation(client, {
+ *   brandId: 'brand-123',
+ *   visitId: 'visit-456',
+ *   confirmationCode: 'ABC123',
+ *   checkIn: '2024-01-01',
+ *   checkOut: '2024-01-05',
+ *   status: 'confirmed'
+ * });
+ * ```
+ */
+export async function createReservation<TClient = any>(
+	client: TClient,
+	input: CreateReservationInput,
+): Promise<any | null> {
+	try {
+		// Validate dates before creating
+		validateDates(input.checkIn, input.checkOut);
+
+		// Calculate nights if not provided
+		if (!input.nights) {
+			const checkInDate = new Date(input.checkIn);
+			const checkOutDate = new Date(input.checkOut);
+			const diffTime = checkOutDate.getTime() - checkInDate.getTime();
+			const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+			input.nights = diffDays;
+		}
+
+		const { data, errors } = await (client as any).models.Reservation.create(input);
+
+		if (errors) {
+			console.error("[createReservation] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data;
+	} catch (error) {
+		if (error instanceof ReservationValidationError) {
+			console.error("[createReservation] Validation error:", error.message);
+			throw error;
+		}
+		console.error("[createReservation] Error creating reservation:", error);
+		throw error;
+	}
+}
+
+/**
+ * Update an existing reservation with validation
+ *
+ * @throws {ReservationValidationError} if dates or status transition is invalid
+ *
+ * @example
+ * ```typescript
+ * import { updateReservation } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const reservation = await updateReservation(client, {
+ *   id: 'reservation-123',
+ *   status: 'checked_in',
+ *   room: '201'
+ * });
+ * ```
+ */
+export async function updateReservation<TClient = any>(
+	client: TClient,
+	input: UpdateReservationInput,
+): Promise<any | null> {
+	try {
+		// If both dates are being updated, validate them
+		if (input.checkIn && input.checkOut) {
+			validateDates(input.checkIn, input.checkOut);
+
+			// Recalculate nights if dates changed
+			const checkInDate = new Date(input.checkIn);
+			const checkOutDate = new Date(input.checkOut);
+			const diffTime = checkOutDate.getTime() - checkInDate.getTime();
+			const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+			input.nights = diffDays;
+		}
+
+		// If status is being updated, validate the transition
+		if (input.status) {
+			// Get current reservation to check current status
+			const { data: currentReservation, errors: getErrors } = await (
+				client as any
+			).models.Reservation.get({ id: input.id });
+
+			if (getErrors || !currentReservation) {
+				console.error("[updateReservation] Error fetching current reservation:", getErrors);
+				return null;
+			}
+
+			const currentStatus = currentReservation.status as ReservationStatus;
+			validateStatusTransition(currentStatus, input.status as ReservationStatus);
+		}
+
+		const { data, errors } = await (client as any).models.Reservation.update(input);
+
+		if (errors) {
+			console.error("[updateReservation] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data;
+	} catch (error) {
+		if (error instanceof ReservationValidationError) {
+			console.error("[updateReservation] Validation error:", error.message);
+			throw error;
+		}
+		console.error("[updateReservation] Error updating reservation:", error);
+		throw error;
+	}
+}
+
+/**
+ * Soft delete a reservation (sets deletedAt/deletedBy instead of removing)
+ *
+ * @example
+ * ```typescript
+ * import { softDeleteReservation } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * await softDeleteReservation(client, 'reservation-123', 'admin@example.com');
+ * ```
+ */
+export async function softDeleteReservation<TClient = any>(
+	client: TClient,
+	id: string,
+	deletedBy: string,
+): Promise<boolean> {
+	try {
+		const { errors } = await (client as any).models.Reservation.update({
+			id,
+			deletedAt: new Date().toISOString(),
+			deletedBy,
+		});
+
+		if (errors) {
+			console.error("[softDeleteReservation] GraphQL errors:", errors);
+			return false;
+		}
+
+		return true;
+	} catch (error) {
+		console.error("[softDeleteReservation] Error soft-deleting reservation:", error);
+		throw error;
+	}
+}
+
+/**
+ * Restore a soft-deleted reservation
+ * Checks retention period before allowing restoration
+ *
+ * @example
+ * ```typescript
+ * import { restoreReservation } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * await restoreReservation(client, 'reservation-123');
+ * // Or with custom retention days:
+ * await restoreReservation(client, 'reservation-123', 60);
+ * ```
+ */
+export async function restoreReservation<TClient = any>(
+	client: TClient,
+	id: string,
+	retentionDays: number = DEFAULT_SOFT_DELETE_RETENTION_DAYS,
+): Promise<{ success: boolean; error?: string }> {
+	try {
+		// First, get the reservation to check its deletedAt timestamp
+		const { data: reservation, errors: getErrors } = await (
+			client as any
+		).models.Reservation.get({ id });
+
+		if (getErrors || !reservation) {
+			console.error("[restoreReservation] Error fetching reservation:", getErrors);
+			return { success: false, error: "Reservation not found" };
+		}
+
+		// Check if restoration is allowed based on retention period
+		const eligibility = checkRestoreEligibility(reservation.deletedAt, retentionDays);
+
+		if (!eligibility.canRestore) {
+			const errorMsg = `Cannot restore reservation. Retention period of ${retentionDays} days has expired. Item was deleted ${eligibility.daysExpired} days ago.`;
+			console.error("[restoreReservation]", errorMsg);
+			return { success: false, error: errorMsg };
+		}
+
+		const { errors } = await (client as any).models.Reservation.update({
+			id,
+			deletedAt: null,
+			deletedBy: null,
+		});
+
+		if (errors) {
+			console.error("[restoreReservation] GraphQL errors:", errors);
+			return { success: false, error: "Failed to restore reservation" };
+		}
+
+		return { success: true };
+	} catch (error) {
+		console.error("[restoreReservation] Error restoring reservation:", error);
+		throw error;
+	}
+}
+
+/**
+ * Hard delete a reservation (permanently removes from database)
+ * Use with caution - prefer softDeleteReservation for recoverable deletion
+ *
+ * @example
+ * ```typescript
+ * import { deleteReservation } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * await deleteReservation(client, 'reservation-123');
+ * ```
+ */
+export async function deleteReservation<TClient = any>(
+	client: TClient,
+	id: string,
+): Promise<boolean> {
+	try {
+		const { errors } = await (client as any).models.Reservation.delete({ id });
+
+		if (errors) {
+			console.error("[deleteReservation] GraphQL errors:", errors);
+			return false;
+		}
+
+		return true;
+	} catch (error) {
+		console.error("[deleteReservation] Error deleting reservation:", error);
+		throw error;
+	}
+}
+
+/**
+ * Update reservation status with validation
+ *
+ * Validates that the status transition is allowed based on current status.
+ * Status transition rules:
+ * - confirmed → checked_in, cancelled, no_show
+ * - checked_in → checked_out, cancelled
+ * - checked_out → (terminal state, no transitions)
+ * - cancelled → (terminal state, no transitions)
+ * - no_show → (terminal state, no transitions)
+ *
+ * @throws {ReservationValidationError} if status transition is invalid
+ *
+ * @example
+ * ```typescript
+ * import { updateReservationStatus } from '@htlkg/data/mutations';
+ * import { generateClient } from '@htlkg/data/client';
+ *
+ * const client = generateClient<Schema>();
+ * const reservation = await updateReservationStatus(
+ *   client,
+ *   'reservation-123',
+ *   'checked_in'
+ * );
+ * ```
+ */
+export async function updateReservationStatus<TClient = any>(
+	client: TClient,
+	id: string,
+	newStatus: ReservationStatus,
+): Promise<any | null> {
+	try {
+		// Get current reservation to check current status
+		const { data: currentReservation, errors: getErrors } = await (
+			client as any
+		).models.Reservation.get({ id });
+
+		if (getErrors || !currentReservation) {
+			console.error("[updateReservationStatus] Error fetching reservation:", getErrors);
+			return null;
+		}
+
+		const currentStatus = currentReservation.status as ReservationStatus;
+
+		// Validate status transition
+		validateStatusTransition(currentStatus, newStatus);
+
+		// Perform the update
+		const { data, errors } = await (client as any).models.Reservation.update({
+			id,
+			status: newStatus,
+		});
+
+		if (errors) {
+			console.error("[updateReservationStatus] GraphQL errors:", errors);
+			return null;
+		}
+
+		return data;
+	} catch (error) {
+		if (error instanceof ReservationValidationError) {
+			console.error("[updateReservationStatus] Validation error:", error.message);
+			throw error;
+		}
+		console.error("[updateReservationStatus] Error updating status:", error);
+		throw error;
+	}
+}