<?php

namespace App\Services\Payment\Contracts;

use App\Models\Withdraw;
use Illuminate\Http\Request;

/**
 * قرارداد درگاه شارژ کیف پول — برای افزودن درگاه جدید این اینترفیس را پیاده کنید.
 */
interface WalletPaymentGatewayInterface
{
    /** شناسه یکتا درگاه، مثلاً montify / payping */
    public function key(): string;

    /** آیا این درگاه برای شارژ آنلاین آماده است؟ (فعال + پیکربندی کامل) */
    public function isAvailable(): bool;

    /**
     * شروع پرداخت و برگرداندن URL هدایت کاربر.
     *
     * @param  array{amount:int, reference_id:string, description?:string, metadata?:array}  $payload
     * @return array{payment_url: string, session_id?: string|null, reference_id?: string, expires_at?: string|null}
     */
    public function initiate(array $payload): array;

    /** آدرس برگشت مرورگر که به پارتنر/درگاه اعلام می‌شود */
    public function returnUrl(): string;

    /** آدرس webhook سرور به سرور */
    public function webhookUrl(): string;

    /**
     * پردازش برگشت مرورگر.
     *
     * @return array{ok: bool, withdraw: ?Withdraw, http_status?: int, message?: string}
     */
    public function handleReturn(Request $request): array;

    /**
     * پردازش برگشت از روی پارامترهای خام — وقتی فرانت query را برای verify می‌فرستد.
     *
     * @param  array<string, mixed>  $rawQuery
     * @return array{ok: bool, withdraw: ?Withdraw, http_status?: int, message?: string}
     */
    public function handleReturnPayload(array $rawQuery): array;

    /**
     * پردازش webhook.
     *
     * @return array{ok: bool, ignored?: bool, http_status?: int, message?: string}
     */
    public function handleWebhook(Request $request): array;
}