<?php
/**
 * Integration interface for implementing external service integrations.
 *
 * @package Awesomemotive\Rewardswp\Interfaces
 * @since 1.0.0
 */

namespace Awesomemotive\Rewardswp\Interfaces;

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

interface IntegrationInterface {
	/**
	 * Classes must implement a method to run hooks to interact with the application.
	 *
	 * @since 1.0.0
	 *
	 * @return void
	 */
	public function init(): void;

	/**
	 * Classes must implement a method to return if the integration is currently installed and active.
	 *
	 * @since 1.0.0
	 *
	 * @return bool Whether the integration is considered active or not.
	 */
	public function is_active(): bool;

	/**
	 * Classes must implement a method to return its unique name.
	 *
	 * @since 1.0.0
	 *
	 * @return string The source name.
	 */
	public function get_source(): string;

	/**
	 * Classes must implement a method to retrieve if a visitor is a customer.
	 *
	 * @since 1.0.0
	 *
	 * @param string $email The visitor email.
	 *
	 * @return bool
	 */
	public function is_customer( string $email ): bool;

	/**
	 * Classes must implement a way to retrieve the customer URL.
	 *
	 * @since 1.0.0
	 *
	 * @param int      $user_id  The user ID.
	 * @param int|null $order_id The order ID (optional).
	 *
	 * @return string The customer URL.
	 */
	public function get_customer_url( int $user_id, ?int $order_id = null ): string;

	/**
	 * Classes must implement a way to retrieve the customer name.
	 *
	 * @since 1.0.0
	 *
	 * @param int|null $order_id The order ID.
	 *
	 * @return string The customer name.
	 */
	public function get_customer_name( ?int $order_id = null ): ?string;

	/**
	 * Classes must implement a way to retrieve the customer email.
	 *
	 * @since 1.0.0
	 *
	 * @param int|null $order_id The order ID.
	 *
	 * @return string The customer email.
	 */
	public function get_customer_email( ?int $order_id = null ): ?string;

	/**
	 * Get customers from the respective system.
	 *
	 * @param array $args     Additional arguments for filtering.
	 * @param int   $page     Current page number.
	 * @param int   $per_page Number of customers per page.
	 * @return array Array of customer data objects. Each array item contains:
	 *               - customer_id (int): The ID of the customer in the system
	 *               - user_id (int|null): WordPress user ID if associated, null otherwise
	 *               - name (string): Customer's full name
	 *               - email (string): Customer's email address
	 *               Returns empty array if no customers found or if system is inactive.
	 */
	public function get_customers( array $args = [], int $page = 1, int $per_page = 10 ): array;

	/**
	 * Get customer orders.
	 *
	 * @since 1.0.0
	 *
	 * @param string $customer_email The customer email.
	 * @param array  $args           Optional. Additional arguments to filter orders.
	 *                                   @type string|array $status    Order status(es). Default 'completed'.
	 *                                   @type int          $limit     Number of orders to return. Default -1 (all).
	 *                                   @type string       $orderby   Order by field. Default 'date'.
	 *                                   @type string       $order     Order direction. Default 'DESC'.
	 * @return array Array of orders with their details.
	 */
	public function get_customer_orders( string $customer_email, array $args = [] ): array;

	/**
	 * Get the store URL.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_store_url(): string;

	/**
	 * Get the number of items in the cart.
	 *
	 * @since 1.1.0
	 *
	 * @return int The number of items in cart.
	 */
	public function get_cart_item_count(): int;

	/**
	 * Get all product IDs currently in the cart.
	 *
	 * @since 1.1.0
	 *
	 * @return array Array of product IDs in cart.
	 */
	public function get_cart_product_ids(): array;

	/**
	 * Get the cart subtotal (before discounts).
	 *
	 * @since 1.2.0
	 *
	 * @return float The cart subtotal.
	 */
	public function get_cart_subtotal(): float;

	/**
	 * Get the checkout page URL.
	 *
	 * @since 1.1.0
	 *
	 * @return string The checkout URL.
	 */
	public function get_checkout_url(): string;

	/**
	 * Get the cart page URL.
	 *
	 * @since 1.1.0
	 *
	 * @return string The cart URL.
	 */
	public function get_cart_url(): string;

	/**
	 * Get the admin link to view an order.
	 *
	 * @since 1.1.0
	 *
	 * @param int $order_id The order ID.
	 *
	 * @return string The admin URL to view the order, or empty string if invalid.
	 */
	public function get_order_link( int $order_id ): string;

	/**
	 * Link guest orders/purchases to a user account.
	 *
	 * Finds all guest orders (where customer_id = 0) with the given email
	 * and updates them to be associated with the new user ID.
	 *
	 * @since 1.2.0
	 *
	 * @param string $email   The billing/customer email to search for.
	 * @param int    $user_id The WordPress user ID to link orders to.
	 *
	 * @return int Number of orders linked.
	 */
	public function link_guest_orders( string $email, int $user_id ): int;

	/**
	 * Count the number of guest orders for a given email.
	 *
	 * Counts orders where customer_id = 0 and the billing/customer email matches.
	 *
	 * @since 1.2.0
	 *
	 * @param string $email The billing/customer email to search for.
	 *
	 * @return int Number of guest orders found.
	 */
	public function count_guest_orders( string $email ): int;

	/**
	 * Store a value in the platform session.
	 *
	 * @since 1.2.0
	 *
	 * @param string $key   The session key.
	 * @param mixed  $value The value to store.
	 *
	 * @return bool True if stored successfully, false otherwise.
	 */
	public function set_session( string $key, $value ): bool;

	/**
	 * Retrieve a value from the platform session.
	 *
	 * @since 1.2.0
	 *
	 * @param string $key The session key.
	 *
	 * @return mixed The stored value, or null if not found.
	 */
	public function get_session( string $key );

	/**
	 * Clear a value from the platform session.
	 *
	 * @since 1.2.0
	 *
	 * @param string $key The session key to clear.
	 *
	 * @return bool True if cleared successfully, false otherwise.
	 */
	public function clear_session( string $key ): bool;
}
