<?php
/**
 * Platform connector contract and registry.
 *
 * A connector transmits invoices to an approved e-invoicing platform (PDP) and
 * reports their lifecycle status. The free plugin ships one connector
 * (SUPER PDP, using the shop's own account). The paid add-on registers a second
 * "managed" connector through the `efacture_fr_connectors` filter without changing
 * any free code — both implement the same interface.
 *
 * @package EFactureFR
 */

defined( 'ABSPATH' ) || exit;

/**
 * Everything a transmission backend must provide.
 *
 * Methods return an associative array on success or a WP_Error on failure, so
 * the caller can surface a human message and decide whether to retry.
 */
interface EFacture_FR_Connector {

	/**
	 * Stable machine id, e.g. 'superpdp'.
	 *
	 * @return string
	 */
	public function id();

	/**
	 * Human label shown in the UI.
	 *
	 * @return string
	 */
	public function label();

	/**
	 * Whether the connector has the credentials it needs to run.
	 *
	 * @return bool
	 */
	public function is_configured();

	/**
	 * Transmit an invoice or credit note (B2B / B2BInt only in the free plugin).
	 *
	 * @param WC_Order $order    Order the document belongs to.
	 * @param string   $pdf_path Absolute path to the Factur-X PDF to send.
	 * @param array    $meta     { external_id, processing_rule, is_credit, number }.
	 * @return array|WP_Error    On success: { submission_id, status, raw }.
	 */
	public function send_invoice( $order, $pdf_path, $meta );

	/**
	 * Fetch the current lifecycle status of a previously sent document.
	 *
	 * @param string $submission_id Id returned by send_invoice().
	 * @return array|WP_Error        On success: { state, codes, raw }.
	 */
	public function get_status( $submission_id );

	/**
	 * Submit a B2C e-reporting period. Not used by the free plugin (B2C sending
	 * is a paid e-reporting feature); the free connector returns a WP_Error.
	 *
	 * @param array $period { from, to, transactions, payments }.
	 * @return array|WP_Error
	 */
	public function send_ereporting( $period );

	/**
	 * List invoices received as a buyer ("factures d'achat"). The free plugin has
	 * no inbox UI; the method exists so the paid add-on can surface it.
	 *
	 * @param string $since ISO date to fetch from.
	 * @return array|WP_Error
	 */
	public function fetch_incoming( $since );
}

/**
 * Connector registry.
 */
class EFacture_FR_Connectors {

	/**
	 * All registered connectors, keyed by id.
	 *
	 * @return EFacture_FR_Connector[]
	 */
	public static function all() {
		$connectors = array();
		$superpdp   = new EFacture_FR_SuperPDP_Connector();
		$connectors[ $superpdp->id() ] = $superpdp;

		/**
		 * Register additional connectors (e.g. the paid "managed" relay connector).
		 *
		 * @param EFacture_FR_Connector[] $connectors Map of id => connector.
		 */
		$connectors = apply_filters( 'efacture_fr_connectors', $connectors );

		// Keep only valid implementations.
		return array_filter(
			$connectors,
			static function ( $c ) {
				return $c instanceof EFacture_FR_Connector;
			}
		);
	}

	/**
	 * The connector that should handle transmission right now.
	 *
	 * Defaults to the selected one (or the first configured one). A paid add-on
	 * can override the choice via the `efacture_fr_active_connector` filter.
	 *
	 * @return EFacture_FR_Connector|null
	 */
	public static function active() {
		$all = self::all();
		if ( empty( $all ) ) {
			return null;
		}

		$selected = (string) get_option( 'efacture_fr_connector', 'superpdp' );
		$active   = isset( $all[ $selected ] ) ? $all[ $selected ] : null;

		if ( ! $active || ! $active->is_configured() ) {
			// Fall back to the first configured connector.
			foreach ( $all as $c ) {
				if ( $c->is_configured() ) {
					$active = $c;
					break;
				}
			}
		}

		/**
		 * Override the active connector.
		 *
		 * @param EFacture_FR_Connector|null $active The chosen connector.
		 * @param EFacture_FR_Connector[]    $all    All registered connectors.
		 */
		return apply_filters( 'efacture_fr_active_connector', $active, $all );
	}
}