<?php
/**
 * Content Store Interface
 *
 * Contract for content index storage and retrieval. All externally-used
 * methods of the content store are defined here.
 *
 * @package Niwa_AI
 * @since   0.10.36
 */

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

interface Niwa_AI_Content_Store_Interface {

	// ── Schema ──

	/**
	 * Create/update database tables.
	 *
	 * @return bool True only when the required schema is verified present.
	 */
	public function ensure_tables();

	// ── Write Operations ──

	/**
	 * Insert or update a batch of rows.
	 *
	 * @param array $rows Array of row arrays.
	 * @return bool
	 */
	public function upsert_batch( $rows );

	/**
	 * Delete a single document by key.
	 *
	 * @param string $doc_key Document key.
	 * @return bool
	 */
	public function delete( $doc_key );

	/**
	 * Delete all documents of a given post type.
	 *
	 * @param string $post_type WordPress post type slug.
	 * @return bool
	 */
	public function delete_by_post_type( $post_type );

	/**
	 * Delete all rows whose doc_key starts with the given prefix.
	 *
	 * @param string $prefix Key prefix.
	 * @return bool
	 */
	public function delete_by_doc_key_prefix( $prefix );

	/**
	 * Build a table row from a document array.
	 *
	 * @param array $doc Document with post data.
	 * @return array Formatted row for table insertion.
	 */
	public function build_row_from_doc( $doc );

	// ── Search ──

	/**
	 * Full-text search with optional filters.
	 *
	 * @param string $query   Search query.
	 * @param int    $limit   Max results (1–30).
	 * @param array  $filters Optional filters (post_type, brand, price_min, price_max, categories, attributes_norm).
	 * @return array
	 */
	public function fulltext_search( $query, $limit = 12, $filters = array() );

	/**
	 * LIKE-based fallback search.
	 *
	 * @param string            $query     Search query.
	 * @param int               $limit     Max results (1–30).
	 * @param string|array|null $post_type Filter by post type.
	 * @return array
	 */
	public function like_search( $query, $limit = 12, $post_type = null );

	// ── Read / Retrieval ──

	/**
	 * Get full product detail by post ID.
	 *
	 * @param int $post_id WordPress post ID.
	 * @return array Product data or empty array.
	 */
	public function get_product_detail( $post_id );

	/**
	 * Get multiple products by their IDs (order preserved).
	 *
	 * @param array $ids Array of post IDs.
	 * @return array
	 */
	public function get_products_by_ids( $ids );

	/**
	 * Get mapping of document names to post IDs.
	 *
	 * @return array
	 */
	public function get_name_to_id_map();

	/**
	 * Count indexed documents by post type.
	 *
	 * @param string $post_type WordPress post type slug.
	 * @return int
	 */
	public function count_by_type( $post_type );

	// ── Store Overview / Summaries ──

	/**
	 * Get store statistics (products, price range, brands, categories, attributes).
	 *
	 * @return array
	 */
	public function get_store_overview();

	/**
	 * Get concatenated site content summaries.
	 *
	 * @param int $snippet_length Max snippet length per document.
	 * @return string
	 */
	public function get_site_content_summaries( $snippet_length = 300 );

	/**
	 * Get home page summary text.
	 *
	 * @param int $max_chars Max characters.
	 * @return string
	 */
	public function get_home_page_summary( $max_chars = 1500 );

	/**
	 * Get agent profile summary text.
	 *
	 * @param int $max_chars Max characters.
	 * @return string
	 */
	public function get_agent_profile_summary( $max_chars = 1500 );

	/**
	 * Get site navigation summary.
	 *
	 * @return string
	 */
	public function get_navigation_summary();

	// ── Embeddings ──

	/**
	 * Get rows pending embedding generation.
	 *
	 * @param int $limit Max rows (1–100).
	 * @return array Rows with doc_key, memory_text, embedding_hash.
	 */
	public function get_pending_embeddings( $limit = 20 );

	/**
	 * Update the embedding vector for a document.
	 *
	 * @param string $doc_key   Document key.
	 * @param array  $embedding Float array.
	 * @param string $hash      Content hash for change detection.
	 * @return bool
	 */
	public function update_embedding( $doc_key, $embedding, $hash );

	/**
	 * Get embeddings for given post IDs.
	 *
	 * @param array $ids Array of post IDs.
	 * @return array
	 */
	public function get_embeddings_by_post_ids( $ids );

	/**
	 * Get a batch of embeddings for iteration.
	 *
	 * @param int   $limit   Max rows (1–500).
	 * @param array $cursor  Stable cursor with post_id and doc_key from the last row.
	 * @param array $filters Optional filters.
	 * @return array
	 */
	public function get_embedding_batch( $limit = 200, $cursor = array(), $filters = array() );

	/**
	 * Get embedding statistics (total, done, pending).
	 *
	 * @return array { total: int, done: int, pending: int }
	 */
	public function get_embedding_stats();
}
