<?php

namespace App\Core\Dns;

/**
 * PRC-95 — DNS provider driver contract.
 *
 * Each driver manages zones + records on its own platform. Records are
 * stored locally (dns_zones / dns_records) as a cache; the driver is
 * the source of truth for actual resolution.
 *
 * Failure → throw exception so the manager can failover (V2).
 */
interface DnsDriverInterface
{
    public function getName(): string;

    public function getLabel(): string;

    public function requiresApiKey(): bool;

    /**
     * Create a new zone for the given domain. Returns provider zone id.
     *
     * @return string provider-side zone id
     */
    public function createZone(string $domain): string;

    /**
     * Delete a zone (idempotent if zone already missing).
     */
    public function deleteZone(string $zoneId): void;

    /**
     * List records for a zone.
     *
     * @return array<int, array{id:string, type:string, name:string, content:string, ttl:int, priority:?int}>
     */
    public function listRecords(string $zoneId): array;

    /**
     * Create a record. Returns provider-side record id.
     *
     * @param  array{type:string, name:string, content:string, ttl?:int, priority?:int, proxied?:bool}  $record
     */
    public function createRecord(string $zoneId, array $record): string;

    public function updateRecord(string $zoneId, string $recordId, array $record): void;

    public function deleteRecord(string $zoneId, string $recordId): void;

    /**
     * Connection test — return ['success' => bool, 'message' => string].
     */
    public function testConnection(): array;

    /**
     * Required configuration fields for admin form.
     *
     * @return array<string, array{type:string, label:string, required?:bool, description?:string}>
     */
    public function adminFields(): array;
}
