<?php

namespace EasyLinkAutomations\Auth\Contracts;

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

/**
 * Interface that all platform auth definitions must implement.
 *
 * Defines the credential schema, authentication headers, and optional
 * test request for a third-party platform.
 */
interface PlatformAuthInterface
{
    /**
     * Unique platform identifier (e.g. 'slack', 'github', 'google_sheets').
     */
    public static function getSlug(): string;

    /**
     * Human-readable platform name.
     */
    public static function getName(): string;

    /**
     * Auth type constant from AuthType class.
     */
    public static function getAuthType(): string;

    /**
     * Credential input fields for the connection form.
     *
     * @return array<string, array{label: string, type: string, required?: bool, placeholder?: string, password?: bool}>
     */
    public static function getFields(): array;

    /**
     * Optional test request to verify credentials work.
     *
     * Return null if testing is not supported.
     *
     * @return array{url: string, method: string, headers?: array}|null
     */
    public static function getTestRequest(): ?array;

    /**
     * Build HTTP headers for authenticating requests to this platform.
     *
     * @param array $credentials The decrypted credential data
     *
     * @return array<string, string> Headers to add to HTTP requests
     */
    public static function authenticate(array $credentials): array;

    /**
     * Serialize platform definition for API/frontend.
     *
     * @return array
     */
    public static function toArray(): array;
}
