<?php

namespace Modules\WhatsApp\Entities\Services;

/**
 * Normalised outcome of a transport send attempt.
 *
 * - ok()      : delivered to the provider; $providerMessageId set.
 * - handoff() : the message was queued onto an async (pull-based) transport such
 *               as the WhatsApp-Web bridge. The driver already set the message
 *               state; the caller leaves it alone — final status arrives via ack.
 * - retry()   : transient problem (channel down, network, rate limit). The caller
 *               keeps the message 'pending' and retries later. NOT a failure.
 * - fail()    : permanent problem (invalid number, rejected template). The caller
 *               marks the message 'failed' and stops.
 */
class SendResult
{
    public bool $success;
    public bool $handedOff;
    public bool $shouldRetry;
    public ?string $providerMessageId;
    public ?string $error;

    private function __construct(bool $success, bool $handedOff, bool $shouldRetry, ?string $providerMessageId, ?string $error)
    {
        $this->success           = $success;
        $this->handedOff         = $handedOff;
        $this->shouldRetry       = $shouldRetry;
        $this->providerMessageId = $providerMessageId;
        $this->error             = $error;
    }

    public static function ok(?string $providerMessageId = null): self
    {
        return new self(true, false, false, $providerMessageId, null);
    }

    public static function handoff(): self
    {
        return new self(false, true, false, null, null);
    }

    public static function retry(string $reason): self
    {
        return new self(false, false, true, null, $reason);
    }

    public static function fail(string $error): self
    {
        return new self(false, false, false, null, $error);
    }
}
