<?php
/**
 * Platform Connector Interface - For real-time imports from external platforms.
 *
 * @package PrimeLink
 */

namespace PrimeLink\Modules\Imports\Connectors;

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

interface PlatformConnectorInterface {

    /**
     * Get connector name.
     *
     * @return string
     */
    public function get_name();

    /**
     * Get connector display name.
     *
     * @return string
     */
    public function get_display_name();

    /**
     * Test connection with platform.
     *
     * @param array $credentials Connection credentials.
     * @return array {success: bool, message: string, data: array}
     */
    public function test_connection( $credentials );

    /**
     * Fetch products from platform.
     *
     * @param array $credentials Connection credentials.
     * @param array $options     Fetch options (limit, offset, filters, etc.).
     * @return array {success: bool, data: array, total: int, has_more: bool}
     */
    public function fetch_products( $credentials, $options = array() );

    /**
     * Fetch orders from platform.
     *
     * @param array $credentials Connection credentials.
     * @param array $options     Fetch options.
     * @return array {success: bool, data: array, total: int, has_more: bool}
     */
    public function fetch_orders( $credentials, $options = array() );

    /**
     * Fetch customers from platform.
     *
     * @param array $credentials Connection credentials.
     * @param array $options     Fetch options.
     * @return array {success: bool, data: array, total: int, has_more: bool}
     */
    public function fetch_customers( $credentials, $options = array() );

    /**
     * Convert platform data to WooCommerce format.
     *
     * @param array $platform_data Platform-specific data.
     * @param string $type        Data type (product, order, customer).
     * @return array WooCommerce-compatible data.
     */
    public function convert_to_woocommerce( $platform_data, $type = 'product' );

    /**
     * Register webhook for real-time sync.
     *
     * @param array $credentials Connection credentials.
     * @param string $event      Event type (product.created, product.updated, etc.).
     * @param string $webhook_url Webhook URL to receive events.
     * @return array {success: bool, webhook_id: string}
     */
    public function register_webhook( $credentials, $event, $webhook_url );

    /**
     * Unregister webhook.
     *
     * @param array $credentials Connection credentials.
     * @param string $webhook_id Webhook ID.
     * @return bool
     */
    public function unregister_webhook( $credentials, $webhook_id );

    /**
     * Get required credentials fields.
     *
     * @return array Array of field definitions.
     */
    public function get_credentials_fields();
}


