package app.closer.domain.repository

import app.closer.domain.model.BucketListItem
import kotlinx.coroutines.flow.Flow

/**
 * Repository for the Couple Bucket List feature.
 *
 * Responsibilities:
 * - Add, update, complete, and delete bucket list items
 * - Observe items in real-time via Firestore snapshot listeners
 * - Query items by category
 */
interface BucketListRepository {

    // ─── CRUD methods ────────────────────────────────────────────────────────

    /** Add a new bucket list item. */
    suspend fun addItem(item: BucketListItem): String

    /** Update an existing bucket list item. */
    suspend fun updateItem(item: BucketListItem)

    /** Get a bucket list item by ID. */
    suspend fun getItem(coupleId: String, itemId: String): BucketListItem?

    /** Get all bucket list items for a couple. */
    suspend fun getItems(coupleId: String): List<BucketListItem>

    /** Delete a bucket list item. */
    suspend fun deleteItem(coupleId: String, itemId: String)

    // ─── Completion methods ──────────────────────────────────────────────────

    /** Mark an item as completed. */
    suspend fun completeItem(coupleId: String, itemId: String, completedBy: String)

    // ─── Category methods ────────────────────────────────────────────────────

    /** Get all items in a specific category. */
    suspend fun getItemsByCategory(coupleId: String, category: String): List<BucketListItem>

    // ─── Observation methods ─────────────────────────────────────────────────

    /** Observe all bucket list items for a couple. */
    fun observeItems(coupleId: String): Flow<List<BucketListItem>>

    /** Observe items in a specific category for a couple. */
    fun observeItemsByCategory(coupleId: String, category: String): Flow<List<BucketListItem>>
}
