<?php
/**
 * HTTP client contract.
 *
 * @package Shiftora\Contracts
 */

declare(strict_types=1);

namespace Shiftora\Contracts;

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Thin wrapper around outbound HTTP calls, decoupled from the concrete
 * HttpClient so callers can swap in a stub.
 */
interface HttpClientInterface {

	/**
	 * Performs a GET request.
	 *
	 * @param array<string,string> $headers Optional HTTP headers.
	 * @param int|null             $timeout Per-request timeout override.
	 * @return array{body: string, code: int, headers: array, effective_url?: string}
	 * @throws \RuntimeException On network or non-2xx error.
	 */
	public function get( string $url, array $headers = [], ?int $timeout = null ): array;

	/**
	 * Performs a POST request with a pre-encoded string body.
	 *
	 * @param string               $body    Pre-encoded body (e.g. JSON).
	 * @param array<string,string> $headers Optional HTTP headers, merged not replaced.
	 * @param int|null             $timeout Per-request timeout override.
	 * @return array{body: string, code: int, headers: array, effective_url?: string, fallback_from_https?: bool}
	 * @throws \RuntimeException On network or non-2xx error.
	 */
	public function post( string $url, string $body = '', array $headers = [], ?int $timeout = null ): array;
}