@voxgig/sdkgen 1.5.1 → 2.0.0

package/project/.sdk/tm/kotlin/utility/Graphql.kt

@@ -0,0 +1,145 @@
+package KOTLINPACKAGE.utility
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Result
+import KOTLINPACKAGE.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.
+
+// Content type every GraphQL-over-HTTP request uses.
+const val GRAPHQL_CONTENT_TYPE = "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`.
+fun graphqlErrorCode(gqlerr: Any?): String {
+  val ext = Struct.getprop(gqlerr, "extensions")
+
+  var code = Struct.getprop(ext, "code") as? String
+  if (code.isNullOrEmpty()) {
+    code = Struct.getprop(ext, "type") as? String
+  }
+  val raw = (code ?: "").uppercase()
+
+  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.
+@Suppress("UNCHECKED_CAST")
+fun graphqlBody(ctx: Context): Any? {
+  val gql = Struct.getprop(ctx.point, "graphql") as? Map<String, Any?>
+    ?: 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 = null != ctx.op && "data" == ctx.op!!.input
+  val src = (if (datainput) ctx.reqdata else ctx.reqmatch) ?: mutableMapOf()
+  val statesrc = (if (datainput) ctx.data else ctx.match) ?: mutableMapOf()
+
+  val variables = mutableMapOf<String, Any?>()
+
+  val varlist = Struct.getprop(gql, "vars") as? List<Any?> ?: emptyList()
+
+  for (entry in varlist) {
+    val spec = entry as? Map<String, Any?> ?: continue
+
+    val name = Struct.getprop(spec, "name") as? String ?: continue
+    val from = Struct.getprop(spec, "from") as? String
+
+    if (from.isNullOrEmpty()) {
+      // The input object IS the request body. Strip the action selector,
+      // which is an SDK-side point discriminator, not an API field.
+      val body = mutableMapOf<String, Any?>()
+      for ((k, v) in src) {
+        if ("\$action" != k) {
+          body[k] = v
+        }
+      }
+      variables[name] = body
+      continue
+    }
+
+    // Only send variables the caller actually supplied: sending an explicit
+    // null would clear a field on many APIs.
+    val value = Struct.getprop(src, from) ?: Struct.getprop(statesrc, from)
+    if (null != value) {
+      variables[name] = value
+    }
+  }
+
+  return mutableMapOf<String, Any?>(
+    "query" to Struct.getprop(gql, "doc"),
+    "variables" to variables,
+  )
+}
+
+// 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.
+fun graphqlErrors(ctx: Context): Boolean {
+  val result = ctx.result ?: return false
+  if (null == ctx.point) return false
+
+  if ("graphql" != Struct.getprop(ctx.point, "kind") as? String) {
+    return false
+  }
+
+  val errors = Struct.getprop(result.body, "errors") as? List<Any?>
+    ?: return false
+  if (errors.isEmpty()) return false
+
+  val first = errors[0]
+  var msg = Struct.getprop(first, "message") as? String
+  if (msg.isNullOrEmpty()) {
+    msg = "graphql error"
+  }
+  if (1 < errors.size) {
+    msg = msg + " (+" + (errors.size - 1) + " more)"
+  }
+
+  result.err = ctx.makeError(graphqlErrorCode(first), "graphql: " + msg)
+  result.ok = false
+
+  return true
+}

package/project/.sdk/tm/kotlin/utility/MakeOptions.kt

@@ -63,7 +63,7 @@ fun makeOptions(ctx: Context): MutableMap<String, Any?> {
       "\"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\": {} } }," +

package/project/.sdk/tm/kotlin/utility/MakeReqRes.kt

@@ -90,6 +90,12 @@ fun makeResponse(ctx: Context): Response {
   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) {

package/project/.sdk/tm/kotlin/utility/MakeSpecUrl.kt

@@ -49,8 +49,23 @@ fun makeSpec(ctx: Context): Spec {
   spec.params = utility.prepareParams(ctx)
   spec.query = utility.prepareQuery(ctx)
   spec.headers = utility.prepareHeaders(ctx)
-  spec.body = utility.prepareBody(ctx)
-  spec.path = utility.preparePath(ctx)
+
+  if ("graphql" == Struct.getprop(ctx.point, "kind") as? String) {
+    // 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.
+    spec.body = utility.graphqlBody(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.
+    spec.query = mutableMapOf()
+    spec.headers["content-type"] = GRAPHQL_CONTENT_TYPE
+  } else {
+    spec.body = utility.prepareBody(ctx)
+    spec.path = utility.preparePath(ctx)
+  }
 
   if (ctx.ctrl.explain != null) {
     ctx.ctrl.explain!!["spec"] = spec

package/project/.sdk/tm/kotlin/utility/Register.kt

@@ -30,6 +30,8 @@ object Register {
     u.prepareParams = ::prepareParams
     u.preparePath = ::preparePath
     u.prepareQuery = ::prepareQuery
+    u.graphqlBody = ::graphqlBody
+    u.graphqlErrors = ::graphqlErrors
     u.resultBasic = ::resultBasic
     u.resultBody = ::resultBody
     u.resultHeaders = ::resultHeaders

package/project/.sdk/tm/lean/src/SdkUtility.lean

@@ -328,6 +328,122 @@ def prepareBody (ctx : Value) : SIO Value := do
   if opInputOf (← opnameOf ctx) == "data" then transformRequest ctx
   else pure .noval
 
+-- ---------------------------------------------------------------------------
+-- graphql (transport)
+--
+-- GraphQL transport. API-INDEPENDENT: every GraphQL SDK this generator
+-- produces uses this code 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.
+-- ---------------------------------------------------------------------------
+
+/-- Content type every GraphQL-over-HTTP request uses. -/
+def graphqlContentType : String := "application/json"
+
+private def hasSub (hay needle : String) : Bool :=
+  1 < (hay.splitOn needle).length
+
+/-- 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 graphqlErrorCode (gqlerr : Value) : SIO String := do
+  let ext ← gp gqlerr "extensions"
+  let c ← gpS ext "code"
+  let code ← if c == "" then gpS ext "type" else pure c
+  let raw := code.toUpper
+  if hasSub raw "AUTH" || hasSub raw "FORBIDDEN" || hasSub raw "UNAUTHENTICATED" then
+    pure "request_auth"
+  else if hasSub raw "RATELIMIT" || hasSub raw "RATE_LIMIT" || hasSub raw "TOO_MANY" then
+    pure "request_ratelimit"
+  else if hasSub raw "BAD_USER_INPUT" || hasSub raw "VALIDATION" || hasSub raw "INVALID" then
+    pure "request_invalid"
+  else
+    pure "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 : Value) : SIO Value := do
+  let gql ← gp (← gp ctx "point") "graphql"
+  match gql with
+  | .map _ => do
+    -- 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.
+    let datainput := opInputOf (← opnameOf ctx) == "data"
+    let reqsrc ← asMap (← gp ctx (if datainput then "reqdata" else "reqmatch"))
+    let datasrc ← asMap (← gp ctx (if datainput then "data" else "match"))
+    let variables ← emptyMap
+    let varlist ← match (← gp gql "vars") with
+      | .list i => listItems i
+      | _ => pure #[]
+    for spec in varlist do
+      match spec with
+      | .map _ => do
+        let name ← gpS spec "name"
+        let from ← gpS spec "from"
+        if name != "" then
+          if from == "" then do
+            -- The input object IS the request body. Strip the action
+            -- selector, which is an SDK-side point discriminator, not an API
+            -- field.
+            let body ← emptyMap
+            for k in (← keysof reqsrc) do
+              if k != "$action" then sp body k (← gp reqsrc k)
+            sp variables name body
+          else do
+            -- Only send variables the caller actually supplied: sending an
+            -- explicit null would clear a field on many APIs.
+            let v0 ← gp reqsrc from
+            let v ← if isNullish v0 then gp datasrc from else pure v0
+            if !(isNullish v) then sp variables name v
+      | _ => pure ()
+    newMap #[("query", ← gp gql "doc"), ("variables", variables)]
+  | _ => pure .noval
+
+/-- 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 : Value) : SIO Bool := do
+  let resultV ← gp ctx "result"
+  match resultV with
+  | .map _ => do
+    if (← gpS (← gp ctx "point") "kind") != "graphql" then pure false
+    else
+      let errors ← match (← gp (← gp resultV "body") "errors") with
+        | .list i => listItems i
+        | _ => pure #[]
+      if errors.size == 0 then pure false
+      else do
+        let first := errors[0]!
+        let m0 ← gpS first "message"
+        let m1 := if m0 == "" then "graphql error" else m0
+        let msg := if 1 < errors.size then
+          m1 ++ " (+" ++ toString (errors.size - 1) ++ " more)" else m1
+        let e ← mkErr (← graphqlErrorCode first) ("graphql: " ++ msg)
+        sp resultV "err" e
+        sp resultV "ok" (.bool false)
+        pure true
+  | _ => pure false
+
 -- ---------------------------------------------------------------------------
 -- result assembly
 -- ---------------------------------------------------------------------------
@@ -404,7 +520,20 @@ def makeSpec (ctx : Value) : SIO (Value × Option Value) := do
   sp spec "path" (.str (← preparePath ctx))
   sp spec "params" (← prepareParams ctx)
   sp spec "query" (← prepareQuery ctx)
-  sp spec "headers" (← prepareHeaders ctx)
+  let headers ← prepareHeaders ctx
+  sp spec "headers" headers
+  if (← gpS point "kind") == "graphql" then do
+    -- 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.
+    sp spec "body" (← graphqlBody ctx)
+    sp spec "path" (.str "")
+    -- 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.
+    sp spec "query" (← emptyMap)
+    sp headers "content-type" (.str graphqlContentType)
   pure (spec, none)
 
 /-- base/prefix/path/suffix joined, `{param}` substituted, query appended. -/
@@ -613,6 +742,10 @@ def makeResponse (ctx : Value) : SIO (Value × Option Value) := do
     resultBasic ctx
     resultHeaders ctx
     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.
+    let _ ← graphqlErrors ctx
     let _ ← transformResponse ctx
     let errv ← gp resultV "err"
     if !(← isErrV errv) then sp resultV "ok" (.bool true)

package/project/.sdk/tm/lua/feature/paging_feature.lua

@@ -13,6 +13,7 @@
 -- configurable.
 
 local BaseFeature = require("feature.base_feature")
+local vs = require("utility.struct.struct")
 
 local PagingFeature = {}
 PagingFeature.__index = PagingFeature
@@ -83,6 +84,14 @@ function PagingFeature:PreRequest(ctx)
     paging = ctx.ctrl.paging
   end
 
+  -- GraphQL paginates through operation VARIABLES, not the query string.
+  -- This hook runs after make_spec, so spec.body already holds the
+  -- { query, variables } envelope, and before make_fetch_def serialises it.
+  if vs.getprop(ctx.point, "kind") == "graphql" then
+    self:_graphql_pre_request(ctx, paging)
+    return
+  end
+
   if paging["cursor"] ~= nil then
     spec.query[cursor_param] = paging["cursor"]
   elseif spec.query[page_param] == nil then
@@ -99,6 +108,47 @@ function PagingFeature:PreRequest(ctx)
 end
 
 
+-- Relay pagination: the cursor is the `after` variable (or whatever the model
+-- named it), and the page size is `first`.
+function PagingFeature:_graphql_pre_request(ctx, paging)
+  local body = ctx.spec.body
+  if type(body) ~= "table" then
+    return
+  end
+
+  local variables = body["variables"]
+  if type(variables) ~= "table" then
+    variables = {}
+    body["variables"] = variables
+  end
+
+  local after_var = self.options["afterVar"] or "after"
+  local first_var = self.options["firstVar"] or "first"
+
+  -- Only bind variables the operation actually declares, or the server
+  -- rejects the document.
+  local declared = {}
+  local varlist = vs.getpath(ctx.point, "graphql.vars")
+  if type(varlist) == "table" then
+    for _, v in ipairs(varlist) do
+      local name = vs.getprop(v, "name")
+      if name ~= nil then
+        declared[name] = true
+      end
+    end
+  end
+
+  if paging["cursor"] ~= nil and declared[after_var] then
+    variables[after_var] = paging["cursor"]
+  end
+
+  if self.options["limit"] ~= nil and variables[first_var] == nil
+    and declared[first_var] then
+    variables[first_var] = self.options["limit"]
+  end
+end
+
+
 function PagingFeature:PreResult(ctx)
   if not self.active then
     return
@@ -131,6 +181,43 @@ function PagingFeature:PreResult(ctx)
     end
   end
 
+  -- Set when the response states hasMore outright, rather than leaving it to
+  -- be inferred from the presence of a cursor.
+  local explicit_more = false
+
+  -- Relay connections carry the cursor in pageInfo, at the path the model
+  -- recorded for this op.
+  local page = vs.getpath(ctx.point, "graphql.page")
+  if type(page) == "table" and type(body) == "table" then
+    -- `connpath` locates the connection object inside the response envelope
+    -- (data.<field>); the cursor/more paths are relative to it.
+    local conn = body
+    local connpath = page["connpath"]
+    if type(connpath) == "string" and connpath ~= "" then
+      local sub = vs.getpath(body, connpath)
+      if sub ~= nil then
+        conn = sub
+      end
+    end
+
+    local cursorpath = page["cursor"]
+    if type(cursorpath) == "string" and cursorpath ~= "" then
+      local cursor = vs.getpath(conn, cursorpath)
+      if cursor ~= nil then
+        paging.cursor = cursor
+      end
+    end
+
+    local morepath = page["more"]
+    if type(morepath) == "string" and morepath ~= "" then
+      local more = vs.getpath(conn, morepath)
+      if type(more) == "boolean" then
+        paging.hasMore = more
+        explicit_more = true
+      end
+    end
+  end
+
   -- Body-level cursors.
   if type(body) == "table" then
     if body["next"] ~= nil and paging.next == nil then
@@ -144,11 +231,19 @@ function PagingFeature:PreResult(ctx)
     end
     if type(body["hasMore"]) == "boolean" then
       paging.hasMore = body["hasMore"]
+      explicit_more = true
     end
   end
 
-  paging.hasMore = paging.hasMore or
-    paging.next ~= nil or paging.cursor ~= nil or paging.nextPage ~= nil
+  -- 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 not explicit_more then
+    paging.hasMore = paging.hasMore or
+      paging.next ~= nil or paging.cursor ~= nil or paging.nextPage ~= nil
+  end
 
   result.paging = paging
 

package/project/.sdk/tm/lua/utility/graphql.lua

@@ -0,0 +1,163 @@
+-- ProjectName SDK utility: graphql
+--
+-- 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:
+--
+--   graphql_body   — build { query, variables } for a point, binding the
+--                    op's arguments to the document's declared variables.
+--
+--   graphql_errors — 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 result_basic
+--                    never sees them.
+
+local vs = require("utility.struct.struct")
+
+local M = {}
+
+-- Content type every GraphQL-over-HTTP request uses.
+M.CONTENT_TYPE = "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`.
+function M.error_code(gqlerr)
+  local ext = vs.getprop(gqlerr, "extensions")
+
+  local raw = vs.getprop(ext, "code")
+  if raw == nil or raw == "" then
+    raw = vs.getprop(ext, "type")
+  end
+  raw = type(raw) == "string" and raw:upper() or ""
+
+  if raw:find("AUTH", 1, true) or raw:find("FORBIDDEN", 1, true)
+    or raw:find("UNAUTHENTICATED", 1, true) then
+    return "request_auth"
+  end
+  if raw:find("RATELIMIT", 1, true) or raw:find("RATE_LIMIT", 1, true)
+    or raw:find("TOO_MANY", 1, true) then
+    return "request_ratelimit"
+  end
+  if raw:find("BAD_USER_INPUT", 1, true) or raw:find("VALIDATION", 1, true)
+    or raw:find("INVALID", 1, true) then
+    return "request_invalid"
+  end
+
+  return "request_graphql"
+end
+
+-- 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.
+function M.body(ctx)
+  local gql = vs.getprop(ctx.point, "graphql")
+  if type(gql) ~= "table" then
+    return nil
+  end
+
+  -- 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.
+  local reqsrc = ctx.reqmatch
+  local datasrc = ctx.match
+  if ctx.op ~= nil and ctx.op.input == "data" then
+    reqsrc = ctx.reqdata
+    datasrc = ctx.data
+  end
+  if type(reqsrc) ~= "table" then
+    reqsrc = {}
+  end
+  if type(datasrc) ~= "table" then
+    datasrc = {}
+  end
+
+  local variables = {}
+
+  local varlist = vs.getprop(gql, "vars")
+  if type(varlist) == "table" then
+    for _, spec in ipairs(varlist) do
+      if type(spec) == "table" then
+        local name = vs.getprop(spec, "name")
+        local from = vs.getprop(spec, "from")
+
+        if name ~= nil then
+          if from == nil or from == "" then
+            -- The input object IS the request body. Strip the action
+            -- selector, which is an SDK-side point discriminator, not an
+            -- API field.
+            local body = {}
+            for k, v in pairs(reqsrc) do
+              if k ~= "$action" then
+                body[k] = v
+              end
+            end
+            variables[name] = body
+          else
+            -- Only send variables the caller actually supplied: sending an
+            -- explicit null would clear a field on many APIs.
+            local val = vs.getprop(reqsrc, from)
+            if val == nil then
+              val = vs.getprop(datasrc, from)
+            end
+            if val ~= nil then
+              variables[name] = val
+            end
+          end
+        end
+      end
+    end
+  end
+
+  return {
+    query = vs.getprop(gql, "doc"),
+    variables = variables,
+  }
+end
+
+-- 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.
+function M.errors(ctx)
+  local result = ctx.result
+  if result == nil or ctx.point == nil then
+    return false
+  end
+
+  if vs.getprop(ctx.point, "kind") ~= "graphql" then
+    return false
+  end
+
+  local errors = vs.getprop(result.body, "errors")
+  if type(errors) ~= "table" or #errors == 0 then
+    return false
+  end
+
+  local first = errors[1]
+  local msg = vs.getprop(first, "message")
+  if type(msg) ~= "string" or msg == "" then
+    msg = "graphql error"
+  end
+  if 1 < #errors then
+    msg = msg .. " (+" .. tostring(#errors - 1) .. " more)"
+  end
+
+  result.err = ctx:make_error(M.error_code(first), "graphql: " .. msg)
+  result.ok = false
+
+  return true
+end
+
+return M

package/project/.sdk/tm/lua/utility/make_options.lua

@@ -66,7 +66,7 @@ local function make_options_util(ctx)
     },
     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`"] = {

package/project/.sdk/tm/lua/utility/make_response.lua

@@ -28,6 +28,12 @@ local function make_response_util(ctx)
   utility.result_basic(ctx)
   utility.result_headers(ctx)
   utility.result_body(ctx)
+
+  -- GraphQL reports failures as a top-level `errors` array under HTTP 200,
+  -- so result_basic's status check never sees them. Lift them here, before
+  -- the response transform tries to unwrap data that is not there.
+  utility.graphql_errors(ctx)
+
   utility.transform_response(ctx)
 
   if result.err == nil then