<?php
/**
 * Result of executing one action step (docs/20 §5).
 *
 * @package Bookline
 */

declare( strict_types=1 );

namespace Bookline\Domain\Automation;

/**
 * Immutable action outcome.
 *
 * @since 0.1.0
 */
final class ActionResult {

	/**
	 * Constructor.
	 *
	 * @param bool                 $ok          Whether the step is a success (including skip/draft).
	 * @param string               $status      completed|skipped|drafted|failed.
	 * @param SkipReason|null      $skip_reason Skip reason.
	 * @param string|null          $rendered    Rendered output.
	 * @param string|null          $error       Error message.
	 * @param bool                 $halt_rest   Cancel remaining steps.
	 * @param int                  $advance     How many step indexes to move forward.
	 * @param array<string, mixed> $extra       Optional step metadata (e.g. notification_log_id).
	 */
	public function __construct(
		private readonly bool $ok,
		private readonly string $status,
		private readonly ?SkipReason $skip_reason = null,
		private readonly ?string $rendered = null,
		private readonly ?string $error = null,
		private readonly bool $halt_rest = false,
		private readonly int $advance = 1,
		private readonly array $extra = [],
	) {}

	/**
	 * Completed send or side effect.
	 *
	 * @param string|null $rendered Rendered output.
	 * @param int         $advance  Step-index delta.
	 *
	 * @since 0.1.0
	 */
	public static function completed( ?string $rendered = null, int $advance = 1, array $extra = [] ): self {
		$steps = $advance < 1 ? 1 : $advance;
		return new self( true, 'completed', null, $rendered, null, false, $steps, $extra );
	}

	/**
	 * Drafted because outbound is disabled.
	 *
	 * @param string|null $rendered Rendered output.
	 *
	 * @since 0.1.0
	 */
	public static function drafted( ?string $rendered = null, array $extra = [] ): self {
		return new self( true, 'drafted', null, $rendered, null, false, 1, $extra );
	}

	/**
	 * Skipped for a documented reason.
	 *
	 * @param SkipReason $reason    Reason.
	 * @param bool       $halt_rest Halt remaining steps.
	 *
	 * @since 0.1.0
	 */
	public static function skipped( SkipReason $reason, bool $halt_rest = false ): self {
		return new self( true, 'skipped', $reason, null, null, $halt_rest );
	}

	/**
	 * Failed.
	 *
	 * @param string $error Error.
	 *
	 * @since 0.1.0
	 */
	public static function failed( string $error ): self {
		return new self( false, 'failed', null, null, $error, true );
	}

	/**
	 * Ok.
	 *
	 * @since 0.1.0
	 */
	public function ok(): bool {
		return $this->ok;
	}

	/**
	 * Status.
	 *
	 * @since 0.1.0
	 */
	public function status(): string {
		return $this->status;
	}

	/**
	 * Skip reason.
	 *
	 * @since 0.1.0
	 */
	public function skip_reason(): ?SkipReason {
		return $this->skip_reason;
	}

	/**
	 * Rendered output.
	 *
	 * @since 0.1.0
	 */
	public function rendered(): ?string {
		return $this->rendered;
	}

	/**
	 * Error.
	 *
	 * @since 0.1.0
	 */
	public function error(): ?string {
		return $this->error;
	}

	/**
	 * Halt remaining.
	 *
	 * @since 0.1.0
	 */
	public function halt_rest(): bool {
		return $this->halt_rest;
	}

	/**
	 * Step-index delta after this result (docs/20 linear engine; used by if/else compile).
	 *
	 * @since 0.1.0
	 */
	public function advance(): int {
		return $this->advance < 1 ? 1 : $this->advance;
	}

	/**
	 * Extra metadata merged into the persisted step row.
	 *
	 * @return array<string, mixed>
	 *
	 * @since 0.1.0
	 */
	public function extra(): array {
		return $this->extra;
	}

	/**
	 * Serialise into a run-step row.
	 *
	 * @return array<string, mixed>
	 *
	 * @since 0.1.0
	 */
	public function to_step_array(): array {
		return array_merge(
			[
				'status'      => $this->status,
				'skip_reason' => $this->skip_reason?->value,
				'rendered'    => $this->rendered,
				'error'       => $this->error,
			],
			$this->extra
		);
	}
}