@voxgig/sdkgen 1.5.1 → 2.0.0

package/project/.sdk/tm/scala/feature/PagingFeature.scala

@@ -1,8 +1,9 @@
 package SCALAPACKAGE.feature
 
-import java.util.{LinkedHashMap, Map => JMap}
+import java.util.{LinkedHashMap, List => JList, Map => JMap}
 import java.util.regex.{Matcher, Pattern}
 import SCALAPACKAGE.core.{Context, SdkClient}
+import SCALAPACKAGE.utility.struct.Struct
 
 // Pagination support for list operations. On the way out (PreRequest) it
 // stamps page/limit (or a cursor) into the request query; on the way back
@@ -52,6 +53,14 @@ class PagingFeature extends BaseFeature("paging", "0.0.1", true) {
       paging = new LinkedHashMap[String, Object]()
     }
 
+    // GraphQL paginates through operation VARIABLES, not the query string.
+    // This hook runs after makeSpec, so spec.body already holds the
+    // { query, variables } envelope, and before makeFetchDef serialises it.
+    if ("graphql" == Struct.getprop(ctx.point, "kind")) {
+      graphqlPreRequest(ctx, paging)
+      return
+    }
+
     val cursor = paging.get("cursor")
     if (cursor != null) {
       spec.query.put(cursorParam, cursor)
@@ -69,6 +78,52 @@ class PagingFeature extends BaseFeature("paging", "0.0.1", true) {
     }
   }
 
+  // Relay pagination: the cursor is the `after` variable (or whatever the
+  // model named it), and the page size is `first`.
+  private def graphqlPreRequest(ctx: Context, paging: JMap[String, Object]): Unit = {
+    val body = ctx.spec.body match {
+      case m: JMap[_, _] => m.asInstanceOf[JMap[String, Object]]
+      case _ => return
+    }
+
+    val variables = body.get("variables") match {
+      case m: JMap[_, _] => m.asInstanceOf[JMap[String, Object]]
+      case _ =>
+        val nv = new LinkedHashMap[String, Object]()
+        body.put("variables", nv)
+        nv
+    }
+
+    val afterVar = FeatureOptions.foptStr(this.options, "afterVar", "after")
+    val firstVar = FeatureOptions.foptStr(this.options, "firstVar", "first")
+
+    // Only bind variables the operation actually declares, or the server
+    // rejects the document.
+    val declared = new java.util.HashSet[String]()
+    Struct.getpath(ctx.point, java.util.List.of("graphql", "vars")) match {
+      case vl: JList[_] =>
+        val it = vl.iterator()
+        while (it.hasNext) {
+          Struct.getprop(it.next(), "name") match {
+            case n: String => declared.add(n)
+            case _ =>
+          }
+        }
+      case _ =>
+    }
+
+    val cursor = paging.get("cursor")
+    if (cursor != null && declared.contains(afterVar)) {
+      variables.put(afterVar, cursor)
+    }
+
+    if (this.options.get("limit") != null && variables.get(firstVar) == null &&
+      declared.contains(firstVar)) {
+      variables.put(firstVar,
+        java.lang.Integer.valueOf(FeatureOptions.foptInt(this.options, "limit", 0)))
+    }
+  }
+
   override def preResult(ctx: Context): Unit = {
     if (!this.active || !isList(ctx)) {
       return
@@ -98,6 +153,45 @@ class PagingFeature extends BaseFeature("paging", "0.0.1", true) {
       case _ =>
     }
 
+    // Set when the response states hasMore outright, rather than leaving it
+    // to be inferred from the presence of a cursor.
+    var explicitMore = false
+
+    // Relay connections carry the cursor in pageInfo, at the path the model
+    // recorded for this op.
+    (Struct.getpath(ctx.point, java.util.List.of("graphql", "page")), body) match {
+      case (pg: JMap[_, _], _: JMap[_, _]) =>
+        val page = pg.asInstanceOf[JMap[String, Object]]
+        // `connpath` locates the connection object inside the response
+        // envelope (data.<field>); the cursor/more paths are relative to it.
+        var conn: Object = body
+        page.get("connpath") match {
+          case cp: String if cp.nonEmpty =>
+            val sub = Struct.getpath(body, cp)
+            if (sub != null) conn = sub
+          case _ =>
+        }
+
+        page.get("cursor") match {
+          case cur: String if cur.nonEmpty =>
+            val c = Struct.getpath(conn, cur)
+            if (c != null) paging.put("cursor", c)
+          case _ =>
+        }
+
+        page.get("more") match {
+          case mp: String if mp.nonEmpty =>
+            Struct.getpath(conn, mp) match {
+              case b: java.lang.Boolean =>
+                paging.put("hasMore", b)
+                explicitMore = true
+              case _ =>
+            }
+          case _ =>
+        }
+      case _ =>
+    }
+
     // Body-level cursors.
     body match {
       case bm0: JMap[_, _] =>
@@ -112,13 +206,20 @@ class PagingFeature extends BaseFeature("paging", "0.0.1", true) {
           paging.put("cursor", bm.get("nextCursor"))
         }
         bm.get("hasMore") match {
-          case b: java.lang.Boolean => paging.put("hasMore", b)
+          case b: java.lang.Boolean =>
+            paging.put("hasMore", b)
+            explicitMore = true
           case _ =>
         }
       case _ =>
     }
 
-    if (!(java.lang.Boolean.TRUE == paging.get("hasMore"))
+    // Cursor presence only INFERS another page. When the server stated the
+    // answer outright — relay's `hasNextPage: false`, or a body `hasMore` —
+    // that wins: a final page normally carries both an end cursor and
+    // hasNextPage false, and inferring from the cursor there would send the
+    // caller back for a page that does not exist, forever.
+    if (!explicitMore && !(java.lang.Boolean.TRUE == paging.get("hasMore"))
         && (paging.get("next") != null || paging.get("cursor") != null
             || paging.get("nextPage") != null)) {
       paging.put("hasMore", java.lang.Boolean.TRUE)

package/project/.sdk/tm/scala/utility/Graphql.scala

@@ -0,0 +1,160 @@
+package SCALAPACKAGE.utility
+
+import java.util.{ArrayList, LinkedHashMap, List => JList, Map => JMap}
+import SCALAPACKAGE.core._
+import SCALAPACKAGE.utility.struct.Struct
+
+// GraphQL transport. API-INDEPENDENT: every GraphQL SDK this generator
+// produces uses this file unchanged. The API-specific part — which
+// operations exist and what each one's document is — is model data,
+// computed once by apidef and emitted into Config.
+//
+// Two jobs:
+//
+//   graphqlBody   — build { query, variables } for a point, binding the
+//                   op's arguments to the document's declared variables.
+//
+//   graphqlErrors — lift a GraphQL failure into an SDK error. GraphQL
+//                   reports failures as a top-level `errors` array under
+//                   HTTP 200, so the status-driven path in resultBasic
+//                   never sees them.
+object Graphql {
+
+  // Content type every GraphQL-over-HTTP request uses.
+  val ContentType: String = "application/json"
+
+  // Map a GraphQL error to the same error codes the HTTP path produces, so
+  // a caller handles auth or rate limiting identically on both transports.
+  // Servers put the machine-readable code in `extensions.code`;
+  // Linear-style APIs use `extensions.type`.
+  def errorCode(gqlerr: Object): String = {
+    val ext = Struct.getprop(gqlerr, "extensions")
+
+    var code = Struct.getprop(ext, "code") match {
+      case s: String => s
+      case _ => ""
+    }
+    if (code == null || code.isEmpty) {
+      code = Struct.getprop(ext, "type") match {
+        case s: String => s
+        case _ => ""
+      }
+    }
+    val raw = code.toUpperCase
+
+    if (raw.contains("AUTH") || raw.contains("FORBIDDEN") ||
+        raw.contains("UNAUTHENTICATED")) return "request_auth"
+    if (raw.contains("RATELIMIT") || raw.contains("RATE_LIMIT") ||
+        raw.contains("TOO_MANY")) return "request_ratelimit"
+    if (raw.contains("BAD_USER_INPUT") || raw.contains("VALIDATION") ||
+        raw.contains("INVALID")) return "request_invalid"
+
+    "request_graphql"
+  }
+
+  // Build the request body for a GraphQL point.
+  //
+  // Variables come from the op's own arguments: a named variable binds to
+  // the like-named argument (`from`), and the input-object variable (empty
+  // `from`) takes the request data as a whole — which is what makes a
+  // generated create/update call look exactly like its REST equivalent.
+  def graphqlBody(ctx: Context): Object = {
+    val gql = Helpers.toMapAny(Struct.getprop(ctx.point, "graphql"))
+    if (gql == null) return null
+
+    // reqmatch/reqdata hold the caller's arguments for THIS call; data/match
+    // hold the entity's current state. Which pair depends on whether the op
+    // takes match or data input. A named variable falls back to the current
+    // state, so updating a loaded entity with just {title} still binds the
+    // stored id the mutation requires.
+    val datainput = ctx.op != null && "data" == ctx.op.input
+    var reqsrc = if (datainput) ctx.reqdata else ctx.reqmatch
+    var datasrc = if (datainput) ctx.data else ctx.matchData
+    if (reqsrc == null) reqsrc = new LinkedHashMap[String, Object]()
+    if (datasrc == null) datasrc = new LinkedHashMap[String, Object]()
+
+    val variables = new LinkedHashMap[String, Object]()
+
+    val varlist = Struct.getprop(gql, "vars") match {
+      case l: JList[_] => l.asInstanceOf[JList[Object]]
+      case _ => new ArrayList[Object]()
+    }
+
+    val it = varlist.iterator()
+    while (it.hasNext) {
+      val spec = Helpers.toMapAny(it.next())
+      if (spec != null) {
+        val name = Struct.getprop(spec, "name") match {
+          case s: String => s
+          case _ => null
+        }
+        val from = Struct.getprop(spec, "from") match {
+          case s: String => s
+          case _ => ""
+        }
+
+        if (name != null) {
+          if (from == null || from.isEmpty) {
+            // The input object IS the request body. Strip the action
+            // selector, which is an SDK-side point discriminator, not an
+            // API field.
+            val body = new LinkedHashMap[String, Object]()
+            val ks = reqsrc.keySet().iterator()
+            while (ks.hasNext) {
+              val k = ks.next()
+              if ("$action" != k) body.put(k, reqsrc.get(k))
+            }
+            variables.put(name, body)
+          } else {
+            // Only send variables the caller actually supplied: sending an
+            // explicit null would clear a field on many APIs.
+            var v = Struct.getprop(reqsrc, from)
+            if (v == null) v = Struct.getprop(datasrc, from)
+            if (v != null) variables.put(name, v)
+          }
+        }
+      }
+    }
+
+    val out = new LinkedHashMap[String, Object]()
+    out.put("query", Struct.getprop(gql, "doc"))
+    out.put("variables", variables)
+    out
+  }
+
+  // Inspect a decoded GraphQL response body and record a failure when the
+  // server reported one. Returns true when an error was recorded.
+  //
+  // Partial data (`data` alongside `errors`) is treated as failure: the
+  // REST surface has no partial-success concept, and silently returning
+  // half an object would be worse than failing.
+  def graphqlErrors(ctx: Context): java.lang.Boolean = {
+    val result = ctx.result
+    if (result == null || ctx.point == null) return false
+
+    val kind = Struct.getprop(ctx.point, "kind") match {
+      case s: String => s
+      case _ => ""
+    }
+    if ("graphql" != kind) return false
+
+    val errors = Struct.getprop(result.body, "errors") match {
+      case l: JList[_] => l.asInstanceOf[JList[Object]]
+      case _ => null
+    }
+    if (errors == null || errors.isEmpty) return false
+
+    val first = errors.get(0)
+    var msg = Struct.getprop(first, "message") match {
+      case s: String => s
+      case _ => ""
+    }
+    if (msg == null || msg.isEmpty) msg = "graphql error"
+    if (1 < errors.size) msg = msg + " (+" + (errors.size - 1) + " more)"
+
+    result.err = ctx.makeError(errorCode(first), "graphql: " + msg)
+    result.ok = false
+
+    true
+  }
+}

package/project/.sdk/tm/scala/utility/Make.scala

@@ -198,7 +198,7 @@ object MakeOptions {
         + "\"headers\": { \"`$CHILD`\": \"`$STRING`\" },"
         + "\"allow\": {"
         + "  \"method\": \"GET,PUT,POST,PATCH,DELETE,OPTIONS\","
-        + "  \"op\": \"create,update,load,list,remove,command,direct\""
+        + "  \"op\": \"create,update,load,list,remove,command,direct,graphql\""
         + "},"
         + "\"entity\": { \"`$CHILD`\": {"
         + "  \"`$OPEN`\": true, \"active\": false, \"alias\": {} } },"
@@ -363,6 +363,12 @@ object MakeResponse {
     utility.resultBasic(ctx)
     utility.resultHeaders(ctx)
     utility.resultBody(ctx)
+
+    // GraphQL reports failures as a top-level `errors` array under HTTP
+    // 200, so resultBasic's status check never sees them. Lift them here,
+    // before the response transform tries to unwrap data that is not there.
+    utility.graphqlErrors(ctx)
+
     utility.transformResponse(ctx)
 
     if (result.err == null) result.ok = true

package/project/.sdk/tm/scala/utility/MakeSpec.scala

@@ -37,8 +37,28 @@ object MakeSpec {
     ctx.spec.params = utility.prepareParams(ctx)
     ctx.spec.query = utility.prepareQuery(ctx)
     ctx.spec.headers = utility.prepareHeaders(ctx)
-    ctx.spec.body = utility.prepareBody(ctx)
-    ctx.spec.path = utility.preparePath(ctx)
+
+    val pkind = Struct.getprop(ctx.point, "kind") match {
+      case s: String => s
+      case _ => ""
+    }
+
+    if ("graphql" == pkind) {
+      // GraphQL addresses one endpoint: no path parts, no query string, and
+      // the body carries the operation. prepareBody is skipped deliberately
+      // — it only emits a body for data-input ops, whereas every GraphQL op
+      // posts one, including load/list/remove.
+      ctx.spec.body = utility.graphqlBody(ctx)
+      ctx.spec.path = ""
+      // prepareQuery already copied the op's match arguments into the query
+      // string. Those same values are bound as operation variables, so
+      // leaving them would send /graphql?id=i1.
+      ctx.spec.query = new LinkedHashMap[String, Object]()
+      ctx.spec.headers.put("content-type", Graphql.ContentType)
+    } else {
+      ctx.spec.body = utility.prepareBody(ctx)
+      ctx.spec.path = utility.preparePath(ctx)
+    }
 
     if (ctx.ctrl.explain != null) ctx.ctrl.explain.put("spec", ctx.spec)
 

package/project/.sdk/tm/scala/utility/Register.scala

@@ -29,6 +29,8 @@ object Register {
     u.prepareParams = (ctx) => PrepareParams.prepareParams(ctx)
     u.preparePath = (ctx) => PreparePath.preparePath(ctx)
     u.prepareQuery = (ctx) => PrepareQuery.prepareQuery(ctx)
+    u.graphqlBody = (ctx) => Graphql.graphqlBody(ctx)
+    u.graphqlErrors = (ctx) => Graphql.graphqlErrors(ctx)
     u.resultBasic = (ctx) => ResultBasic.resultBasic(ctx)
     u.resultBody = (ctx) => ResultBody.resultBody(ctx)
     u.resultHeaders = (ctx) => ResultHeaders.resultHeaders(ctx)

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/core/Utility.swift

@@ -29,6 +29,8 @@ public final class Utility {
   public var prepareParams: ((Context) -> VMap)!
   public var preparePath: ((Context) -> String)!
   public var prepareQuery: ((Context) -> VMap)!
+  public var graphqlBody: ((Context) -> Value)!
+  public var graphqlErrors: ((Context) -> Bool)!
   public var resultBasic: ((Context) -> Result)!
   public var resultBody: ((Context) -> Result)!
   public var resultHeaders: ((Context) -> Result)!
@@ -70,6 +72,8 @@ public final class Utility {
     u.prepareParams = src.prepareParams
     u.preparePath = src.preparePath
     u.prepareQuery = src.prepareQuery
+    u.graphqlBody = src.graphqlBody
+    u.graphqlErrors = src.graphqlErrors
     u.resultBasic = src.resultBasic
     u.resultBody = src.resultBody
     u.resultHeaders = src.resultHeaders

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/feature/PagingFeature.swift

@@ -48,6 +48,14 @@ public final class PagingFeature: BaseFeature {
     // A per-call cursor/page from ctrl takes priority (auto-iteration).
     let paging = ctx.ctrl.paging
 
+    // GraphQL paginates through operation VARIABLES, not the query string.
+    // This hook runs after makeSpec, so spec.body already holds the
+    // { query, variables } envelope, and before makeFetchDef serialises it.
+    if "graphql" == gp(ctx.point, "kind").asString {
+      graphqlPreRequest(ctx, paging)
+      return
+    }
+
     var cursor: Value = .noval
     var hasCursor = false
     if let paging = paging {
@@ -71,6 +79,49 @@ public final class PagingFeature: BaseFeature {
     }
   }
 
+  // Relay pagination: the cursor is the `after` variable (or whatever the
+  // model named it), and the page size is `first`.
+  private func graphqlPreRequest(_ ctx: Context, _ paging: VMap?) {
+    guard let spec = ctx.spec, let body = spec.body.asMap else {
+      return
+    }
+
+    let variables: VMap
+    if let v = body.entries["variables"]?.asMap {
+      variables = v
+    }
+    else {
+      variables = VMap()
+      body.entries["variables"] = .map(variables)
+    }
+
+    let afterVar = foptStr(options, "afterVar", "after")
+    let firstVar = foptStr(options, "firstVar", "first")
+
+    // Only bind variables the operation actually declares, or the server
+    // rejects the document.
+    var declared: Set<String> = []
+    if let varlist = gpath(ctx.point, "graphql", "vars").asList {
+      for v in varlist.items {
+        if let name = gp(v, "name").asString {
+          declared.insert(name)
+        }
+      }
+    }
+
+    if let paging = paging {
+      let cursor = gp(paging, "cursor")
+      if !isNil(cursor) && declared.contains(afterVar) {
+        variables.entries[afterVar] = cursor
+      }
+    }
+
+    if !isNil(fopt(options, "limit")) && isNil(gp(variables, firstVar))
+      && declared.contains(firstVar) {
+      variables.entries[firstVar] = .int(Int64(foptInt(options, "limit", 0)))
+    }
+  }
+
   public override func preResult(_ ctx: Context) {
     if !active || !isList(ctx) {
       return
@@ -98,6 +149,34 @@ public final class PagingFeature: BaseFeature {
       }
     }
 
+    // Set when the response states hasMore outright, rather than leaving it
+    // to be inferred from the presence of a cursor.
+    var explicitMore = false
+
+    // Relay connections carry the cursor in pageInfo, at the path the model
+    // recorded for this op.
+    if let page = gpath(ctx.point, "graphql", "page").asMap, nil != body.asMap {
+      // `connpath` locates the connection object inside the response
+      // envelope (data.<field>); the cursor/more paths are relative to it.
+      var conn = body
+      if let connpath = gp(page, "connpath").asString, !connpath.isEmpty {
+        let sub = getpath(body, jtpv(connpath.split(separator: ".").map(String.init)))
+        if !isNil(sub) { conn = sub }
+      }
+
+      if let cursorpath = gp(page, "cursor").asString, !cursorpath.isEmpty {
+        let c = getpath(conn, jtpv(cursorpath.split(separator: ".").map(String.init)))
+        if !isNil(c) { paging.entries["cursor"] = c }
+      }
+
+      if let morepath = gp(page, "more").asString, !morepath.isEmpty {
+        if let more = getpath(conn, jtpv(morepath.split(separator: ".").map(String.init))).asBool {
+          paging.entries["hasMore"] = .bool(more)
+          explicitMore = true
+        }
+      }
+    }
+
     // Body-level cursors.
     if let bm = body.asMap {
       let next = gp(bm, "next")
@@ -114,11 +193,17 @@ public final class PagingFeature: BaseFeature {
       }
       if let hmb = gp(bm, "hasMore").asBool {
         paging.entries["hasMore"] = .bool(hmb)
+        explicitMore = true
       }
     }
 
+    // Cursor presence only INFERS another page. When the server stated the
+    // answer outright - relay's `hasNextPage: false`, or a body `hasMore` -
+    // that wins: a final page normally carries both an end cursor and
+    // hasNextPage false, and inferring from the cursor there would send the
+    // caller back for a page that does not exist, forever.
     let hasMoreNow = gp(paging, "hasMore").asBool ?? false
-    if !hasMoreNow &&
+    if !explicitMore && !hasMoreNow &&
       (!isNil(gp(paging, "next")) || !isNil(gp(paging, "cursor")) || !isNil(gp(paging, "nextPage"))) {
       paging.entries["hasMore"] = .bool(true)
     }

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/utility/Graphql.swift

@@ -0,0 +1,142 @@
+import Foundation
+
+// GraphQL transport. API-INDEPENDENT: every GraphQL SDK this generator
+// produces uses this file unchanged. The API-specific part — which
+// operations exist and what each one's document is — is model data,
+// computed once by apidef and emitted into Config.
+//
+// Two jobs:
+//
+//   graphqlBodyUtil   — build { query, variables } for a point, binding the
+//                       op's arguments to the document's declared variables.
+//
+//   graphqlErrorsUtil — lift a GraphQL failure into an SDK error. GraphQL
+//                       reports failures as a top-level `errors` array under
+//                       HTTP 200, so the status-driven path in resultBasic
+//                       never sees them.
+
+/// Content type every GraphQL-over-HTTP request uses.
+let graphqlContentType = "application/json"
+
+/// Map a GraphQL error to the same error codes the HTTP path produces, so a
+/// caller handles auth or rate limiting identically on both transports.
+/// Servers put the machine-readable code in `extensions.code`; Linear-style
+/// APIs use `extensions.type`.
+func graphqlErrorCode(_ gqlerr: Value) -> String {
+  let ext = gp(gqlerr, "extensions")
+
+  var code = gp(ext, "code").asString ?? ""
+  if code.isEmpty {
+    code = gp(ext, "type").asString ?? ""
+  }
+  let raw = code.uppercased()
+
+  if raw.contains("AUTH") || raw.contains("FORBIDDEN")
+    || raw.contains("UNAUTHENTICATED") {
+    return "request_auth"
+  }
+  if raw.contains("RATELIMIT") || raw.contains("RATE_LIMIT")
+    || raw.contains("TOO_MANY") {
+    return "request_ratelimit"
+  }
+  if raw.contains("BAD_USER_INPUT") || raw.contains("VALIDATION")
+    || raw.contains("INVALID") {
+    return "request_invalid"
+  }
+
+  return "request_graphql"
+}
+
+/// Build the request body for a GraphQL point.
+///
+/// Variables come from the op's own arguments: a named variable binds to the
+/// like-named argument (`from`), and the input-object variable (empty
+/// `from`) takes the request data as a whole — which is what makes a
+/// generated create/update call look exactly like its REST equivalent.
+func graphqlBodyUtil(_ ctx: Context) -> Value {
+  let gql = gp(ctx.point, "graphql")
+  guard nil != gql.asMap else { return .noval }
+
+  // reqmatch/reqdata hold the caller's arguments for THIS call; data/match
+  // hold the entity's current state. Which pair depends on whether the op
+  // takes match or data input. A named variable falls back to the current
+  // state, so updating a loaded entity with just {title} still binds the
+  // stored id the mutation requires.
+  var reqsrc = ctx.reqmatch
+  var datasrc = ctx.match
+  if let op = ctx.op, "data" == op.input {
+    reqsrc = ctx.reqdata
+    datasrc = ctx.data
+  }
+
+  let variables = VMap()
+
+  if let varlist = gp(gql, "vars").asList {
+    for spec in varlist.items {
+      guard nil != spec.asMap else { continue }
+
+      let name = gp(spec, "name").asString ?? ""
+      if name.isEmpty { continue }
+
+      let from = gp(spec, "from").asString ?? ""
+
+      if from.isEmpty {
+        // The input object IS the request body. Strip the action selector,
+        // which is an SDK-side point discriminator, not an API field.
+        let body = VMap()
+        for item in items(.map(reqsrc)) {
+          let key = item[0].asString ?? ""
+          if "$action" != key {
+            body.entries[key] = item[1]
+          }
+        }
+        variables.entries[name] = .map(body)
+        continue
+      }
+
+      // Only send variables the caller actually supplied: sending an
+      // explicit null would clear a field on many APIs.
+      var val = gp(.map(reqsrc), from)
+      if isNil(val) {
+        val = gp(.map(datasrc), from)
+      }
+      if !isNil(val) {
+        variables.entries[name] = val
+      }
+    }
+  }
+
+  let out = VMap()
+  out.entries["query"] = gp(gql, "doc")
+  out.entries["variables"] = .map(variables)
+
+  return .map(out)
+}
+
+/// Inspect a decoded GraphQL response body and record a failure when the
+/// server reported one. Returns true when an error was recorded.
+///
+/// Partial data (`data` alongside `errors`) is treated as failure: the REST
+/// surface has no partial-success concept, and silently returning half an
+/// object would be worse than failing.
+@discardableResult
+func graphqlErrorsUtil(_ ctx: Context) -> Bool {
+  guard let result = ctx.result else { return false }
+
+  guard "graphql" == gp(ctx.point, "kind").asString else { return false }
+
+  guard let errors = gp(result.body, "errors").asList else { return false }
+  if errors.items.isEmpty { return false }
+
+  let first = errors.items[0]
+  var msg = gp(first, "message").asString ?? ""
+  if msg.isEmpty { msg = "graphql error" }
+  if 1 < errors.items.count {
+    msg = msg + " (+\(errors.items.count - 1) more)"
+  }
+
+  result.err = ctx.makeError(graphqlErrorCode(first), "graphql: " + msg)
+  result.ok = false
+
+  return true
+}