<?php

namespace Alexr\Whatsapp\Contracts;

use Alexr\Whatsapp\DTO\NormalizedMessage;
use Alexr\Whatsapp\DTO\NormalizedStatusUpdate;
use Alexr\Whatsapp\DTO\SendMessageRequest;
use Alexr\Whatsapp\DTO\SendTemplateRequest;

/**
 * Interface WhatsappProviderInterface
 *
 * Contract for WhatsApp service providers (Twilio, 360dialog, etc.)
 * All providers must implement this interface to ensure consistent behavior.
 *
 * @package Alexr\Whatsapp\Contracts
 */
interface WhatsappProviderInterface
{
	/**
	 * Get the provider identifier
	 *
	 * @return string Provider name (e.g., 'twilio', '360dialog')
	 */
	public function getProviderName(): string;

	/**
	 * Check if the provider is properly configured
	 *
	 * @return bool
	 */
	public function isConfigured(): bool;

	/**
	 * Test connection to the provider's API
	 *
	 * @return array ['success' => bool, 'message' => string, 'data' => array]
	 */
	public function testConnection(): array;

	/**
	 * Send a free-form text message
	 * Note: Only works within 24h window after customer-initiated conversation
	 *
	 * @param SendMessageRequest $request
	 * @return array ['success' => bool, 'message' => string, 'data' => array]
	 */
	public function sendMessage(SendMessageRequest $request): array;

	/**
	 * Send a template message
	 *
	 * @param SendTemplateRequest $request
	 * @return array ['success' => bool, 'message' => string, 'data' => array]
	 */
	public function sendTemplate(SendTemplateRequest $request): array;

	/**
	 * Get list of available templates
	 *
	 * @param int $pageSize Number of templates to fetch
	 * @param string|null $cursor Pagination cursor
	 * @return array ['success' => bool, 'message' => string, 'data' => array]
	 */
	public function getTemplates(int $pageSize = 50, ?string $cursor = null): array;

	/**
	 * Get a single template by ID
	 *
	 * @param string $templateId Provider-specific template ID
	 * @return array ['success' => bool, 'message' => string, 'data' => array]
	 */
	public function getTemplate(string $templateId): array;

	/**
	 * Get message status from provider
	 *
	 * @param string $messageId Provider-specific message ID
	 * @return array ['success' => bool, 'message' => string, 'data' => array]
	 */
	public function getMessageStatus(string $messageId): array;

	/**
	 * Parse incoming webhook payload into normalized format
	 *
	 * @param array $payload Raw webhook payload
	 * @return NormalizedMessage
	 */
	public function parseIncomingWebhook(array $payload): NormalizedMessage;

	/**
	 * Parse status callback webhook into normalized format
	 *
	 * @param array $payload Raw webhook payload
	 * @return NormalizedStatusUpdate
	 */
	public function parseStatusCallback(array $payload): NormalizedStatusUpdate;

	/**
	 * Validate webhook signature
	 *
	 * @param string $signature The signature header value
	 * @param string $url The webhook URL
	 * @param array $payload The webhook payload
	 * @return bool
	 */
	public function validateWebhookSignature(string $signature, string $url, array $payload): bool;

	/**
	 * Generate webhook response in provider-specific format
	 *
	 * @param string|null $replyMessage Optional message to send back
	 * @return string
	 */
	public function generateWebhookResponse(?string $replyMessage = null): string;

	/**
	 * Get the content type for webhook responses
	 *
	 * @return string
	 */
	public function getWebhookResponseContentType(): string;

	/**
	 * Get webhook URL for incoming messages
	 *
	 * @return string
	 */
	public function getIncomingWebhookUrl(): string;

	/**
	 * Get webhook URL for status callbacks
	 *
	 * @return string
	 */
	public function getStatusCallbackUrl(): string;

	/**
	 * Get the phone number used by this provider
	 *
	 * @return string
	 */
	public function getPhoneNumber(): string;

	/**
	 * Get provider-specific configuration
	 *
	 * @return array
	 */
	public function getConfig(): array;

	/**
	 * Check if payload is a status callback
	 *
	 * @param array $payload
	 * @return bool
	 */
	public function isStatusCallback(array $payload): bool;

	/**
	 * Check if payload is an incoming message
	 *
	 * @param array $payload
	 * @return bool
	 */
	public function isIncomingMessage(array $payload): bool;

	/**
	 * Mark an inbound message as read, sending a read receipt to the customer's WhatsApp
	 *
	 * @param string $messageId Provider-specific message ID (Twilio SID or WhatsApp wamid)
	 * @return array ['success' => bool, 'message' => string, 'data' => array]
	 */
	public function markAsRead(string $messageId): array;

	/**
	 * Check if a phone number is registered on WhatsApp
	 *
	 * @param string $phone Phone number in international format (e.g. +34612345678)
	 * @return array ['success' => bool, 'has_whatsapp' => bool|null, 'wa_id' => string|null]
	 */
	public function checkContact(string $phone): array;
}