From 428c64a46ac9c3b5cf6ce01a902279a6cfb5fe44 Mon Sep 17 00:00:00 2001
From: Keith Solomon <keith@vincentdesign.ca>
Date: Tue, 28 Apr 2026 06:24:02 -0500
Subject: [PATCH] feat: add rest transport exception

---
 src/Transport/RestTransportException.php      | 57 +++++++++++++++++++
 .../Transport/RestTransportExceptionTest.php  | 27 +++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 src/Transport/RestTransportException.php
 create mode 100644 tests/Unit/Transport/RestTransportExceptionTest.php

diff --git a/src/Transport/RestTransportException.php b/src/Transport/RestTransportException.php
new file mode 100644
index 0000000..461659b
--- /dev/null
+++ b/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;
+	}
+}
diff --git a/tests/Unit/Transport/RestTransportExceptionTest.php b/tests/Unit/Transport/RestTransportExceptionTest.php
new file mode 100644
index 0000000..25fdba9
--- /dev/null
+++ b/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() );
+	}
+}