Merge branch 'main' into claude/action-attempt-status-annotations-f216kn

Author: razor-x

README.md

@@ -559,24 +559,39 @@ The Seam API parses these params with the corresponding [parser].
 [reference implementation]: https://github.com/seamapi/url-search-params-serializer
 [parser]: https://github.com/seamapi/url-search-params-parser
 
-#### Errors
+### Error Handling
 
 Every exception the SDK raises implements `Seam\SeamException`, so it can be
 caught as a group. An API error is a `Seam\HttpApiError` carrying
 `getErrorCode()`, `getStatusCode()` and `getRequestId()`, with
 `Seam\HttpUnauthorizedError` and `Seam\HttpInvalidInputError` as the two
 specific cases worth catching on their own.
 
+#### Validation errors
+
+When the API rejects a request because a parameter is invalid, it throws an
+`HttpInvalidInputError`. Look up messages for a parameter you are already
+rendering, for example a field in a form:
+
 ```php
-use Seam\HttpApiError;
 use Seam\HttpInvalidInputError;
 
 try {
-    $seam->devices->get(device_id: $device_id);
+    $seam->devices->list(device_ids: ["not-a-uuid"]);
 } catch (HttpInvalidInputError $error) {
-    print_r($error->getValidationErrorMessages("device_id"));
-} catch (HttpApiError $error) {
-    print $error->getErrorCode();
+    print_r($error->getValidationErrorMessages("device_ids"));
+}
+```
+
+Or read every parameter that failed validation to summarize the request:
+
+```php
+foreach ($error->validation_errors as $validation_error) {
+    printf(
+        "%s: %s\n",
+        $validation_error->parameter_name,
+        implode(", ", $validation_error->error_messages),
+    );
 }
 ```
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapi/php",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "type": "module",
   "private": true,
   "license": "MIT",

package.json

@@ -7,7 +7,14 @@
  */
 class HttpInvalidInputError extends HttpApiError
 {
-    private object $validationErrors;
+    private object $rawValidationErrors;
+
+    /**
+     * Validation errors, one entry per failed request parameter.
+     *
+     * @var list<ValidationError>
+     */
+    public readonly array $validation_errors;
 
     public function __construct(
         object $error,
@@ -16,7 +23,21 @@ public function __construct(
     ) {
         parent::__construct($error, $statusCode, $requestId);
         $this->errorCode = "invalid_input";
-        $this->validationErrors = $error->validation_errors ?? (object) [];
+        $this->rawValidationErrors = $error->validation_errors ?? (object) [];
+
+        $validationErrors = [];
+        foreach (
+            get_object_vars($this->rawValidationErrors)
+            as $paramName => $_
+        ) {
+            if ($paramName !== "_errors") {
+                $validationErrors[] = new ValidationError(
+                    $paramName,
+                    $this->getValidationErrorMessages($paramName),
+                );
+            }
+        }
+        $this->validation_errors = $validationErrors;
     }
 
     /**
@@ -27,6 +48,6 @@ public function __construct(
      */
     public function getValidationErrorMessages(string $paramName): array
     {
-        return $this->validationErrors->{$paramName}->_errors ?? [];
+        return $this->rawValidationErrors->{$paramName}->_errors ?? [];
     }
 }

src/HttpInvalidInputError.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Seam;
+
+/**
+ * A request parameter that failed validation and its error messages.
+ */
+final class ValidationError
+{
+    /**
+     * @param string[] $error_messages
+     */
+    public function __construct(
+        public readonly string $parameter_name,
+        public readonly array $error_messages,
+    ) {}
+}

src/ValidationError.php

@@ -10,7 +10,7 @@ class Version
      * Injected from package.json when a version is cut, by the version
      * lifecycle script in package.json. Do not edit by hand.
      */
-    public const VERSION = "4.3.0";
+    public const VERSION = "4.4.0";
 
     public static function get(): string
     {

src/Version.php

@@ -8,6 +8,7 @@
 use Seam\HttpInvalidInputError;
 use Seam\HttpUnauthorizedError;
 use Seam\Seam;
+use Seam\ValidationError;
 use Tests\Support\FakeSeamConnectTestCase;
 
 final class HttpErrorTest extends FakeSeamConnectTestCase
@@ -65,9 +66,38 @@ public function testThrowsInvalidInputErrorWithValidationMessages(): void
                 ["Expected array, received number"],
                 $error->getValidationErrorMessages("device_ids"),
             );
+            $this->assertEquals(
+                [
+                    new ValidationError("device_ids", [
+                        "Expected array, received number",
+                    ]),
+                ],
+                $error->validation_errors,
+            );
         }
     }
 
+    public function testValidationErrorsExcludeRequestWideErrors(): void
+    {
+        $error = new HttpInvalidInputError(
+            (object) [
+                "validation_errors" => (object) [
+                    "_errors" => ["Request is invalid"],
+                    "device_ids" => (object) [
+                        "_errors" => ["Invalid device IDs"],
+                    ],
+                ],
+            ],
+            400,
+            null,
+        );
+
+        $this->assertEquals(
+            [new ValidationError("device_ids", ["Invalid device IDs"])],
+            $error->validation_errors,
+        );
+    }
+
     public function testValidationMessagesAreEmptyForAnUnknownParam(): void
     {
         try {