/**
 * Type definitions for the async in-memory processing queue
 *
 * This module defines the core data structures for queue items,
 * status updates, and callbacks used throughout the queue system.
 */

import type { ProgressEvent } from '$lib/server/extraction';

/**
 * Possible states for a queue item
 * - pending: Waiting in queue to be processed
 * - in_progress: Currently being processed through one of the phases
 * - success: All phases completed successfully
 * - unhealthy: Recoverable error occurred, can be retried
 * - error: Non-recoverable error occurred
 */
export type QueueItemStatus = 'pending' | 'in_progress' | 'success' | 'unhealthy' | 'error';

/**
 * Processing phases for queue items
 * - extraction: Extracting content from Instagram
 * - parsing: Parsing recipe from extracted text
 * - uploading: Uploading recipe to Tandoor
 */
export type ProcessingPhase = 'extraction' | 'parsing' | 'uploading';

/**
 * Phase progress information
 * Tracks the status of each processing phase
 */
export interface PhaseProgress {
	/** Name of the phase */
	name: ProcessingPhase;
	/** Current status of this phase */
	status: 'pending' | 'in_progress' | 'completed' | 'error';
	/** When phase started processing (ISO 8601 string) */
	startedAt?: string;
	/** When phase completed (ISO 8601 string) */
	completedAt?: string;
	/** Error message if phase failed */
	error?: string;
}

/**
 * Processing results wrapper
 * Contains all outputs from the processing pipeline
 */
export interface ProcessingResults {
	/** Extracted text from Instagram */
	extractedText?: string;
	/** Thumbnail URL or data URL */
	thumbnail?: string | null;
	/** Parsed recipe object */
	recipe?: any;
	/** Tandoor recipe ID */
	tandoorRecipeId?: number;
	/** Tandoor recipe URL (constructed from ID) */
	tandoorUrl?: string;
}

/**
 * Queue item representing a single Instagram URL processing job
 */
export interface QueueItem {
	/** Unique identifier (UUID) */
	id: string;

	/** Instagram URL to process */
	url: string;

	/** Current status of the item */
	status: QueueItemStatus;

	// Phase tracking
	/** Current processing phase (only set when status is in_progress) */
	currentPhase?: ProcessingPhase;

	/** Array of all phases with their progress status */
	phases: PhaseProgress[];

	// Timestamps
	/** When item was added to queue (ISO 8601 string) */
	enqueuedAt: string;

	/** Alias for enqueuedAt (frontend uses this) */
	createdAt: string;

	/** When processing started (ISO 8601 string) */
	startedAt?: string;

	/** When processing completed (ISO 8601 string) */
	completedAt?: string;

	/** Last update timestamp (ISO 8601 string) */
	updatedAt?: string;

	// Results - wrapped in results object
	/** Processing results container */
	results?: ProcessingResults;

	// Legacy direct properties (kept for transition period)
	/** @deprecated Use results.extractedText instead */
	extractedText?: string;

	/** @deprecated Use results.thumbnail instead */
	thumbnail?: string | null;

	/** @deprecated Use results.recipe instead */
	recipe?: any;

	/** @deprecated Use results.tandoorRecipeId instead */
	tandoorRecipeId?: number;

	// Progress tracking
	/** User-facing log messages */
	logs: string[];

	/** All SSE progress events received */
	progressEvents: ProgressEvent[];

	// Error handling
	/** Error details if processing failed */
	error?: {
		/** Phase where error occurred */
		phase: ProcessingPhase;
		/** Error message */
		message: string;
		/** Whether error is recoverable (can retry) */
		recoverable: boolean;
		/** When error occurred (ISO 8601 string) */
		timestamp: string;
	};

	// Retry tracking
	/** Number of times this item has been retried */
	retryCount: number;

	/** Maximum number of retries allowed */
	maxRetries: number;
}

/**
 * Update notification sent to queue subscribers
 */
export interface QueueStatusUpdate {
	/** Type of update */
	type: 'status_change' | 'progress' | 'phase_complete';

	/** ID of the item that was updated */
	itemId: string;

	/** New status of the item */
	status: QueueItemStatus;

	/** When update occurred (ISO 8601 string) */
	timestamp: string;

	/** URL of the item */
	url?: string;

	// Phase information
	/** Current phase (if status is in_progress) */
	phase?: ProcessingPhase;

	/** Full phase progress array */
	progress?: PhaseProgress[];

	// Results
	/** Processing results object */
	results?: ProcessingResults;

	// Error
	/** Error information */
	error?: any;

	/** Additional data related to the update (legacy) */
	data?: any;
}

/**
 * Callback function for queue update notifications
 */
export type QueueUpdateCallback = (update: QueueStatusUpdate) => void;
