Include GraphQL error messages in HTTP error responses (#15)

When the API returns non-OK HTTP status codes (401, 403, 429, etc.),
the client now reads the response body and appends the actual error
messages from the GraphQL errors array. This surfaces details like
which permissions are missing instead of only showing generic messages.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: mattvagni

packages/sdk/src/graphql-client.ts

@@ -56,16 +56,28 @@ export class PlainGraphQLClient {
     });
 
     if (!response.ok) {
+      const errorDetail = await this.extractErrorMessage(response);
+
       if (response.status === 401) {
-        throw new AuthenticationError("Invalid API key");
+        throw new AuthenticationError(
+          errorDetail ? `Authentication error: ${errorDetail}` : "Authentication error",
+        );
       }
       if (response.status === 403) {
-        throw new ForbiddenError("Insufficient permissions");
+        throw new ForbiddenError(
+          errorDetail ? `Insufficient permissions: ${errorDetail}` : "Insufficient permissions",
+        );
       }
       if (response.status === 429) {
-        throw new RateLimitError("Rate limit exceeded");
+        throw new RateLimitError(
+          errorDetail ? `Rate limit exceeded: ${errorDetail}` : "Rate limit exceeded",
+        );
       }
-      throw new NetworkError(`HTTP ${response.status}: ${response.statusText}`);
+      throw new NetworkError(
+        errorDetail
+          ? `HTTP ${response.status}: ${response.statusText}: ${errorDetail}`
+          : `HTTP ${response.status}: ${response.statusText}`,
+      );
     }
 
     const json = (await response.json()) as GraphQLResponse<TData>;
@@ -80,4 +92,16 @@ export class PlainGraphQLClient {
 
     return json.data;
   }
+
+  private async extractErrorMessage(response: Response): Promise<string | undefined> {
+    try {
+      const json = (await response.json()) as GraphQLResponse<unknown>;
+      if (json.errors && json.errors.length > 0) {
+        return json.errors.map((e) => e.message).join("; ");
+      }
+    } catch {
+      // Response body wasn't valid JSON — fall back to default message
+    }
+    return undefined;
+  }
 }