fix: Raise a Seam error for a success response that is malformed

README.md

@@ -539,8 +539,10 @@ try {
 }
 ```
 
-A response that is not shaped like a Seam error, such as a gateway returning
-HTML, raises the underlying Guzzle exception instead.
+An error response that is not shaped like a Seam error, such as a gateway
+returning HTML, raises the underlying Guzzle exception instead. A successful
+response that does not carry the resource the endpoint returns raises
+`Seam\InvalidResponseError`, with `getPath()` and `getKey()`.
 
 ## Development and Testing
 

codegen/layouts/partials/route-method.hbs

@@ -29,7 +29,7 @@
 {{#if usesActionAttempt}}
 
         return ResolveActionAttempt::resolve_action_attempt(
-            {{returnResource}}::from_json($res->{{returnPath}}),
+            {{returnResource}}::from_json(Body::read($res, "{{returnPath}}", "{{path}}")),
             $this->client,
             $wait_for_action_attempt ?? $this->defaults["wait_for_action_attempt"]
         );
@@ -43,9 +43,9 @@
 {{#unless returnsVoid}}
 
 {{#if isArrayResponse}}
-        return array_map(fn ($r) => {{returnResource}}::from_json($r), $res->{{returnPath}});
+        return array_map(fn ($r) => {{returnResource}}::from_json($r), Body::read_list($res, "{{returnPath}}", "{{path}}"));
 {{else}}
-        return {{returnResource}}::from_json($res->{{returnPath}});
+        return {{returnResource}}::from_json(Body::read($res, "{{returnPath}}", "{{path}}"));
 {{/if}}
 {{/unless}}
 {{/if}}

src/Http/Body.php

@@ -4,6 +4,7 @@
 
 use GuzzleHttp\Utils;
 use Psr\Http\Message\ResponseInterface;
+use Seam\InvalidResponseError;
 
 /**
  * Reads the JSON body of a response.
@@ -38,4 +39,55 @@ public static function decode(ResponseInterface $response): mixed
             return null;
         }
     }
+
+    /**
+     * Reads the resource an endpoint returns out of its response envelope.
+     *
+     * @throws InvalidResponseError If the envelope does not carry the key
+     */
+    public static function read(mixed $res, string $key, string $path): mixed
+    {
+        if (!is_object($res)) {
+            throw new InvalidResponseError(
+                $path,
+                $key,
+                "got " . get_debug_type($res) . " instead of a response object",
+            );
+        }
+
+        if (!property_exists($res, $key)) {
+            throw new InvalidResponseError(
+                $path,
+                $key,
+                "which the response does not contain",
+            );
+        }
+
+        return $res->$key;
+    }
+
+    /**
+     * Reads a list of resources out of a response envelope.
+     *
+     * @return array<array-key, mixed>
+     *
+     * @throws InvalidResponseError If the envelope does not carry a list
+     */
+    public static function read_list(
+        mixed $res,
+        string $key,
+        string $path,
+    ): array {
+        $value = self::read($res, $key, $path);
+
+        if (!is_array($value)) {
+            throw new InvalidResponseError(
+                $path,
+                $key,
+                "got " . get_debug_type($value) . " instead of a list",
+            );
+        }
+
+        return $value;
+    }
 }

src/Http/ResolveActionAttempt.php

@@ -6,6 +6,7 @@
 use Seam\ActionAttemptFailedError;
 use Seam\ActionAttemptTimeoutError;
 use Seam\InvalidOptionsError;
+use Seam\InvalidResponseError;
 use Seam\Resources\ActionAttempt;
 
 /**
@@ -105,12 +106,14 @@ private static function get_action_attempt(
         );
 
         $action_attempt = ActionAttempt::from_json(
-            $res->action_attempt ?? null,
+            Body::read($res, "action_attempt", "/action_attempts/get"),
         );
 
         if ($action_attempt === null) {
-            throw new \UnexpectedValueException(
-                "Seam returned no action attempt for {$action_attempt_id}",
+            throw new InvalidResponseError(
+                "/action_attempts/get",
+                "action_attempt",
+                "which was empty for {$action_attempt_id}",
             );
         }
 

src/InvalidResponseError.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Seam;
+
+/**
+ * Error thrown when a successful response does not carry the resource the
+ * endpoint is defined to return.
+ */
+class InvalidResponseError extends \UnexpectedValueException implements
+    SeamException
+{
+    public function __construct(
+        private string $path,
+        private string $key,
+        string $reason,
+    ) {
+        parent::__construct(
+            "Seam returned an invalid response for {$path}: expected \"{$key}\", {$reason}",
+        );
+    }
+
+    /**
+     * The endpoint path the response came from, e.g. `/devices/get`.
+     */
+    public function getPath(): string
+    {
+        return $this->path;
+    }
+
+    /**
+     * The response key that should have carried the resource.
+     */
+    public function getKey(): string
+    {
+        return $this->key;
+    }
+}