<?php
/**
 * File Path: includes/import/class-mbs-parent-importer-csv.php
 *
 * Parent CSV Importer Orchestrator (Thin Wrapper)
 *
 * This is the new public API entry point that replaces the old monolithic
 * class-mbs-importer-csv.php. It maintains 100% backward compatibility for
 * all existing calls from the Import/Export tab, JS handlers, and other
 * importers.
 *
 * Delegates heavy lifting to child classes in includes/import/csv/ for
 * better maintainability and to prevent truncation issues.
 *
 * Available on the FREE tier. Importing is never license-gated (the license gates display, not import).
 *
 * @package MyBookShowroom
 * @since   1.0.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

// Load all child classes early (critical for AJAX handlers)
require_once dirname( __FILE__ ) . '/csv/class-mbs-child-importer-csv-helpers.php';
require_once dirname( __FILE__ ) . '/csv/class-mbs-child-importer-csv-parse.php';
require_once dirname( __FILE__ ) . '/csv/class-mbs-child-importer-csv-map.php';
require_once dirname( __FILE__ ) . '/csv/class-mbs-child-importer-csv-insert.php';
require_once dirname( __FILE__ ) . '/csv/class-mbs-child-importer-csv-process.php';
// Format support: XLSX reading and ZIP extraction.
require_once dirname( __FILE__ ) . '/class-mbs-xlsx-reader.php';
require_once dirname( __FILE__ ) . '/class-mbs-zip-extractor.php';

/**
 * Main CSV importer parent class.
 *
 * Provides the same public static interface as the old class while delegating
 * to specialized child classes.
 */
class MBS_Parent_Importer_CSV { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound -- mbs_/MBS_ prefix is correct; scanner not configured with plugin prefix

	/**
	 * Parse headers from an uploaded CSV file and return detected columns
	 * plus a first-row preview for the column-mapping UI in Tab 5.
	 *
	 * @param string $file_path Absolute path to the uploaded temporary file.
	 * @return array{
	 *   success: bool,
	 *   columns: string[],
	 *   preview: array[],
	 *   error: string
	 * }
	 */
	public static function parse_headers( string $file_path ): array {
		return MBS_Child_Importer_CSV_Parse::parse_headers( $file_path );
	}

	/**
	 * Import a CSV file.
	 *
	 * Importing is free (no license gate); the license gates data display, not import.
	 *
	 * @param string $file_path         Absolute path to the uploaded file.
	 * @param array  $column_map        CSV column → MBS field name map from the UI.
	 *                                  When empty, columns are auto-matched by name.
	 * @param array  $force_insert_keys ISBN-13 or title-slug keys approved for
	 *                                  force-insert despite duplicate detection.
	 * @param array  $options           Optional runtime flags (see Process child class).
	 *                                  Supported keys:
	 *                                  - images_dir (string): directory of bundled
	 *                                    cover images from a ZIP import.
	 * @return array{
	 *   success: bool,
	 *   inserted: int,
	 *   skipped: int,
	 *   duplicates: array[],
	 *   errors: string[],
	 *   error: string
	 * }
	 */
	public static function import(
		string $file_path,
		array  $column_map = array(),
		array  $force_insert_keys = array(),
		array  $options = array()
	): array {
		return MBS_Child_Importer_CSV_Process::import( $file_path, $column_map, $force_insert_keys, $options );
	}

	/**
	 * Insert a batch of pre-validated candidate arrays directly (no CSV parsing).
	 *
	 * Used by the mbs_import_candidates AJAX action to insert candidates returned
	 * by the Google Books and Open Library importers after admin confirmation.
	 *
	 * @param array[] $candidates       Pre-built candidate arrays with at least 'title'.
	 * @param array   $force_insert_keys Keys approved for force-insert on duplicate.
	 * @return array Same shape as import().
	 */
	public static function import_candidates(
		array $candidates,
		array $force_insert_keys = array()
	): array {
		return MBS_Child_Importer_CSV_Process::import_candidates( $candidates, $force_insert_keys );
	}

	/**
	 * Insert a single pre-validated book candidate.
	 *
	 * Public static so the mbs_import_candidates AJAX handler can call it directly.
	 *
	 * @param array $candidate Candidate array.
	 * @return true|string True on success, error message string on failure.
	 */
	public static function insert_book( array $candidate ): true|string {
		return MBS_Child_Importer_CSV_Insert::insert_book( $candidate );
	}

	/**
	 * Get the canonical list of accepted columns (for UI mapping).
	 *
	 * @return string[]
	 */
	public static function get_accepted_columns(): array {
		return MBS_Child_Importer_CSV_Helpers::get_accepted_columns();
	}

	/**
	 * Get the maximum allowed file size in bytes.
	 *
	 * @return int
	 */
	public static function get_max_file_size(): int {
		return MBS_Child_Importer_CSV_Helpers::get_max_file_size();
	}
}
