feat: add rest transport exception

src/Transport/RestTransportException.php

@@ -0,0 +1,57 @@
+<?php
+/**
+ * Typed REST transport failure.
+ *
+ * @package WPContentSync
+ */
+
+namespace WPContentSync\Transport;
+
+final class RestTransportException extends \RuntimeException {
+	/** @var array<string, mixed> */
+	private array $context;
+
+	private string $failure_code;
+
+	/**
+	 * @param array<string, mixed> $context Failure context.
+	 */
+	private function __construct( string $failure_code, string $message, array $context = array() ) {
+		parent::__construct( $message );
+
+		$this->failure_code = $failure_code;
+		$this->context      = $context;
+	}
+
+	/**
+	 * @param array<string, mixed> $context Failure context.
+	 */
+	public static function connectionFailed( string $message, array $context = array() ): self {
+		return new self( 'connection_failed', $message, $context );
+	}
+
+	/**
+	 * @param array<string, mixed> $context Failure context.
+	 */
+	public static function authenticationFailed( string $message, array $context = array() ): self {
+		return new self( 'authentication_failed', $message, $context );
+	}
+
+	/**
+	 * @param array<string, mixed> $context Failure context.
+	 */
+	public static function remoteRejected( string $message, array $context = array() ): self {
+		return new self( 'remote_rejected', $message, $context );
+	}
+
+	public function failureCode(): string {
+		return $this->failure_code;
+	}
+
+	/**
+	 * @return array<string, mixed>
+	 */
+	public function context(): array {
+		return $this->context;
+	}
+}

tests/Unit/Transport/RestTransportExceptionTest.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace WPContentSync\Tests\Unit\Transport;
+
+use PHPUnit\Framework\TestCase;
+use WPContentSync\Transport\RestTransportException;
+
+class RestTransportExceptionTest extends TestCase {
+	public function test_it_exposes_transport_failure_context(): void {
+		$exception = RestTransportException::connectionFailed(
+			'Connection timed out.',
+			array( 'url' => 'https://example.test/wp-json/wp-content-sync/v1/status' )
+		);
+
+		self::assertSame( 'connection_failed', $exception->failureCode() );
+		self::assertSame( 'Connection timed out.', $exception->getMessage() );
+		self::assertSame( array( 'url' => 'https://example.test/wp-json/wp-content-sync/v1/status' ), $exception->context() );
+	}
+
+	public function test_it_exposes_authentication_failures(): void {
+		$exception = RestTransportException::authenticationFailed( 'REST authentication failed.' );
+
+		self::assertSame( 'authentication_failed', $exception->failureCode() );
+		self::assertSame( 'REST authentication failed.', $exception->getMessage() );
+		self::assertSame( array(), $exception->context() );
+	}
+}