@voxgig/sdkgen 1.5.0 → 2.0.0

package/project/.sdk/tm/haskell/src/SdkRuntime.hs

@@ -415,6 +415,136 @@ prepareBodyUtil ctx = do
   op <- readIORef (cOp ctx)
   if opInput op == "data" then transformRequestUtil ctx else pure VNoval
 
+-- ------------------------------------------------------------------
+-- 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:
+--
+--   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.
+graphqlContentType :: String
+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`.
+graphqlErrorCode :: Value -> IO String
+graphqlErrorCode gqlerr = do
+  ext <- getp gqlerr "extensions"
+  c0 <- getStrD ext "code" ""
+  code <- if null c0 then getStrD ext "type" "" else pure c0
+  let raw = map toUpper code
+  pure $
+    if substrContains raw "AUTH" || substrContains raw "FORBIDDEN"
+         || substrContains raw "UNAUTHENTICATED"
+      then "request_auth"
+      else if substrContains raw "RATELIMIT" || substrContains raw "RATE_LIMIT"
+                || substrContains raw "TOO_MANY"
+        then "request_ratelimit"
+        else if substrContains raw "BAD_USER_INPUT"
+                  || substrContains raw "VALIDATION"
+                  || substrContains raw "INVALID"
+          then "request_invalid"
+          else "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.
+graphqlBodyUtil :: Context -> IO Value
+graphqlBodyUtil ctx = do
+  point <- readIORef (cPoint ctx)
+  gql <- getp point "graphql"
+  case gql of
+    VMap _ -> 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.
+      op <- readIORef (cOp ctx)
+      let datainput = opInput op == "data"
+      rsV <- readIORef (if datainput then cReqdata ctx else cReqmatch ctx)
+      dsV <- readIORef (if datainput then cData ctx else cMatch ctx)
+      reqsrc <- case rsV of VMap _ -> pure rsV; _ -> emptyMap
+      datasrc <- case dsV of VMap _ -> pure dsV; _ -> emptyMap
+      variables <- emptyMap
+      vl <- getp gql "vars"
+      varlist <- case vl of VList _ -> listItems vl; _ -> pure []
+      forM_ varlist $ \spec -> case spec of
+        VMap _ -> do
+          name <- getStrD spec "name" ""
+          from <- getStrD spec "from" ""
+          when (not (null name)) $
+            if null 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.
+                body <- emptyMap
+                ks <- keysof reqsrc
+                forM_ ks $ \k -> when (k /= "$action") $ do
+                  v <- getp reqsrc k
+                  setp body k v
+                setp variables name body
+              else do
+                -- Only send variables the caller actually supplied: sending
+                -- an explicit null would clear a field on many APIs.
+                v0 <- getp reqsrc from
+                val <- if isNullish v0 then getp datasrc from else pure v0
+                when (not (isNullish val)) (setp variables name val)
+        _ -> pure ()
+      doc <- getp gql "doc"
+      jo [("query", doc), ("variables", variables)]
+    _ -> pure VNoval
+
+-- 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.
+graphqlErrorsUtil :: Context -> IO Bool
+graphqlErrorsUtil ctx = do
+  resultV <- readIORef (cResult ctx)
+  point <- readIORef (cPoint ctx)
+  kind <- getStrD point "kind" ""
+  case resultV of
+    VMap _ | kind == "graphql" -> do
+      body <- getp resultV "body"
+      ev <- getp body "errors"
+      errors <- case ev of VList _ -> listItems ev; _ -> pure []
+      if null errors
+        then pure False
+        else do
+          let firsterr = head errors
+              n = length errors
+          m0 <- getStrD firsterr "message" ""
+          let m1 = if null m0 then "graphql error" else m0
+              msg = if 1 < n then m1 ++ " (+" ++ show (n - 1) ++ " more)" else m1
+          code <- graphqlErrorCode firsterr
+          e <- mkErr code ("graphql: " ++ msg)
+          setp resultV "err" e
+          setp resultV "ok" (VBool False)
+          pure True
+    _ -> pure False
+
 prepareAuthUtil :: Context -> UResult
 prepareAuthUtil ctx = do
   specV <- readIORef (cSpec ctx)
@@ -642,8 +772,23 @@ makeSpecUtil ctx = do
           params <- prepareParamsUtil ctx; setp sp "params" params
           query <- prepareQueryUtil ctx; setp sp "query" query
           headers <- prepareHeadersUtil ctx; setp sp "headers" headers
-          body <- prepareBodyUtil ctx; setp sp "body" body
-          path <- preparePathUtil ctx; setp sp "path" (VStr path)
+          kind <- getStrD point "kind" ""
+          if kind == "graphql"
+            -- 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.
+            then do
+              body <- graphqlBodyUtil ctx; setp sp "body" body
+              setp sp "path" (VStr "")
+              -- 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.
+              emptyq <- emptyMap; setp sp "query" emptyq
+              setp headers "content-type" (VStr graphqlContentType)
+            else do
+              body <- prepareBodyUtil ctx; setp sp "body" body
+              path <- preparePathUtil ctx; setp sp "path" (VStr path)
           ctrl <- readIORef (cCtrl ctx)
           explain <- getp ctrl "explain"
           case explain of { VMap _ -> do { snap <- specToValue sp; setp explain "spec" snap }; _ -> pure () }
@@ -780,6 +925,11 @@ makeResponseUtil ctx = do
             VMap _ -> do
               setp specV "step" (VStr "response")
               resultBasicUtil ctx; resultHeadersUtil ctx; resultBodyUtil 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.
+              _ <- graphqlErrorsUtil ctx
               _ <- transformResponseUtil ctx
               errv <- getp resultV "err"
               isErrR <- isErr errv
@@ -866,7 +1016,7 @@ optSpecValue :: IO Value
 optSpecValue = do
   auth <- jo [("prefix", VStr "")]
   hdrs <- jo [("`$CHILD`", VStr "`$STRING`")]
-  allow <- jo [("method", VStr "GET,PUT,POST,PATCH,DELETE,OPTIONS"), ("op", VStr "create,update,load,list,remove,command,direct")]
+  allow <- jo [("method", VStr "GET,PUT,POST,PATCH,DELETE,OPTIONS"), ("op", VStr "create,update,load,list,remove,command,direct,graphql")]
   entChild <- do a <- emptyMap; jo [("`$OPEN`", VBool True), ("active", VBool False), ("alias", a)]
   ent <- jo [("`$CHILD`", entChild)]
   featChild <- jo [("`$OPEN`", VBool True), ("active", VBool False)]

package/project/.sdk/tm/java/core/SdkClient.java

@@ -176,7 +176,100 @@ public abstract class SdkClient {
     return utility.makeFetchDef.apply(ctx);
   }
 
+  /**
+   * Raw endpoint access is operator-controllable, like every entity op.
+   * Blocking it means denying BOTH the 'direct' and 'graphql' tokens, since
+   * either one reaches the same endpoint.
+   */
   public Map<String, Object> direct(Map<String, Object> fetchargs) {
+    if (!opAllowed("direct")) {
+      return opDenied("direct");
+    }
+
+    return rawRequest(fetchargs);
+  }
+
+  /** Is this raw-access op permitted by the SDK's allow.op option? */
+  private boolean opAllowed(String op) {
+    Object allow = Struct.getpath(this.options, List.of("allow", "op"));
+    return allow instanceof String && ((String) allow).contains(op);
+  }
+
+  private Map<String, Object> opDenied(String op) {
+    Object allow = Struct.getpath(this.options, List.of("allow", "op"));
+    Map<String, Object> out = new LinkedHashMap<>();
+    out.put("ok", false);
+    out.put("err", new SdkError(op + "_allow",
+        "ProjectNameSDK: " + op + ": operation not allowed by"
+        + " SDK option allow.op value: \""
+        + (allow instanceof String ? allow : "") + "\"", null));
+    return out;
+  }
+
+  /**
+   * Raw GraphQL access: the pressure valve that makes the generated
+   * surface's deliberate omissions (per-call selection sets, typed filter
+   * builders, batching, subscriptions) livable — the whole schema stays
+   * reachable.
+   *
+   * <p>Thin wrapper over the same prepare/fetch path direct uses, with the
+   * one thing raw direct cannot do for GraphQL: a GraphQL failure rides HTTP
+   * 200 as a top-level {@code errors} array, so status alone would report a
+   * failed query as ok.
+   *
+   * <p>NOTE: like direct, this bypasses the feature pipeline — no retry,
+   * ratelimit or paging features apply.
+   */
+  public Map<String, Object> graphql(String query,
+      Map<String, Object> variables, Map<String, Object> ctrl) {
+
+    if (!opAllowed("graphql")) {
+      return opDenied("graphql");
+    }
+
+    Map<String, Object> headers = new LinkedHashMap<>();
+    headers.put("content-type", "application/json");
+
+    Map<String, Object> body = new LinkedHashMap<>();
+    body.put("query", query);
+    body.put("variables", variables == null ? new LinkedHashMap<>() : variables);
+
+    Map<String, Object> fetchargs = new LinkedHashMap<>();
+    fetchargs.put("method", "POST");
+    fetchargs.put("headers", headers);
+    fetchargs.put("body", body);
+    fetchargs.put("ctrl", ctrl == null ? new LinkedHashMap<>() : ctrl);
+
+    Map<String, Object> res = rawRequest(fetchargs);
+
+    // Errors are read BEFORE any status check: a GraphQL parse or validation
+    // failure comes back as HTTP 400 carrying the standard { errors: [...] }
+    // body, and the raw path represents a non-2xx as ok:false with no err —
+    // so returning early on status would discard the server's own
+    // diagnostics, which are the only useful part of that response.
+    Object errors = Struct.getpath(res, List.of("data", "errors"));
+
+    if (errors instanceof List && !((List<Object>) errors).isEmpty()) {
+      Object first = ((List<Object>) errors).get(0);
+      Object m = Struct.getprop(first, "message");
+      String msg = m instanceof String && !((String) m).isEmpty()
+          ? (String) m : "graphql error";
+      res.put("ok", false);
+      res.put("err", new SdkError("graphql_error",
+          "ProjectNameSDK: graphql: " + msg, null));
+      res.put("graphql", errors);
+    }
+
+    return res;
+  }
+
+  /**
+   * Ungated request path shared by direct and graphql, each of which checks
+   * its own allow.op token first. Private, rather than a flag on fetchargs:
+   * a caller-supplied marker would let anyone opt straight back out of the
+   * gate by passing it.
+   */
+  private Map<String, Object> rawRequest(Map<String, Object> fetchargs) {
     Utility utility = this.utility;
 
     if (fetchargs == null) {

package/project/.sdk/tm/java/core/Utility.java

@@ -74,6 +74,8 @@ public class Utility {
   public CtxFn<Map<String, Object>> prepareParams;
   public CtxFn<String> preparePath;
   public CtxFn<Map<String, Object>> prepareQuery;
+  public CtxFn<Object> graphqlBody;
+  public CtxFn<Result> graphqlErrors;
   public CtxFn<Result> resultBasic;
   public CtxFn<Result> resultBody;
   public CtxFn<Result> resultHeaders;
@@ -115,6 +117,8 @@ public class Utility {
     u.prepareParams = this.prepareParams;
     u.preparePath = this.preparePath;
     u.prepareQuery = this.prepareQuery;
+    u.graphqlBody = this.graphqlBody;
+    u.graphqlErrors = this.graphqlErrors;
     u.resultBasic = this.resultBasic;
     u.resultBody = this.resultBody;
     u.resultHeaders = this.resultHeaders;

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

@@ -1,7 +1,9 @@
 package JAVAPACKAGE.feature;
 
 import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Set;
 import java.util.Map;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -10,6 +12,7 @@ import JAVAPACKAGE.core.Context;
 import JAVAPACKAGE.core.Result;
 import JAVAPACKAGE.core.SdkClient;
 import JAVAPACKAGE.core.Spec;
+import JAVAPACKAGE.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
@@ -66,6 +69,14 @@ public class PagingFeature extends BaseFeature {
       paging = new LinkedHashMap<>();
     }
 
+    // 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".equals(Struct.getprop(ctx.point, "kind", null))) {
+      graphqlPreRequest(ctx, paging);
+      return;
+    }
+
     Object cursor = paging.get("cursor");
     if (cursor != null) {
       spec.query.put(cursorParam, cursor);
@@ -85,6 +96,51 @@ public class PagingFeature extends BaseFeature {
     }
   }
 
+  // Relay pagination: the cursor is the `after` variable (or whatever the
+  // model named it), and the page size is `first`.
+  @SuppressWarnings("unchecked")
+  private void graphqlPreRequest(Context ctx, Map<String, Object> paging) {
+    if (!(ctx.spec.body instanceof Map)) {
+      return;
+    }
+    Map<String, Object> body = (Map<String, Object>) ctx.spec.body;
+
+    Object varsval = body.get("variables");
+    Map<String, Object> variables;
+    if (varsval instanceof Map) {
+      variables = (Map<String, Object>) varsval;
+    }
+    else {
+      variables = new LinkedHashMap<>();
+      body.put("variables", variables);
+    }
+
+    String afterVar = FeatureOptions.foptStr(this.options, "afterVar", "after");
+    String firstVar = FeatureOptions.foptStr(this.options, "firstVar", "first");
+
+    // Only bind variables the operation actually declares, or the server
+    // rejects the document.
+    Set<String> declared = new LinkedHashSet<>();
+    Object varlist = Struct.getpath(ctx.point, List.of("graphql", "vars"));
+    if (varlist instanceof List) {
+      for (Object v : (List<Object>) varlist) {
+        Object name = Struct.getprop(v, "name", null);
+        if (name instanceof String) {
+          declared.add((String) name);
+        }
+      }
+    }
+
+    if (paging.get("cursor") != null && declared.contains(afterVar)) {
+      variables.put(afterVar, paging.get("cursor"));
+    }
+
+    if (this.options.get("limit") != null && variables.get(firstVar) == null
+        && declared.contains(firstVar)) {
+      variables.put(firstVar, FeatureOptions.foptInt(this.options, "limit", 0));
+    }
+  }
+
   @Override
   public void preResult(Context ctx) {
     if (!this.active || !isList(ctx)) {
@@ -113,6 +169,43 @@ public class PagingFeature extends BaseFeature {
       }
     }
 
+    // Set when the response states hasMore outright, rather than leaving it
+    // to be inferred from the presence of a cursor.
+    boolean explicitMore = false;
+
+    // Relay connections carry the cursor in pageInfo, at the path the model
+    // recorded for this op.
+    Object page = Struct.getpath(ctx.point, List.of("graphql", "page"));
+    if (page instanceof Map && body instanceof Map) {
+      // `connpath` locates the connection object inside the response
+      // envelope (data.<field>); the cursor/more paths are relative to it.
+      Object connpath = Struct.getprop(page, "connpath", null);
+      Object conn = body;
+      if (connpath instanceof String && !"".equals(connpath)) {
+        Object sub = Struct.getpath(body, connpath);
+        if (sub != null) {
+          conn = sub;
+        }
+      }
+
+      Object cursorpath = Struct.getprop(page, "cursor", null);
+      if (cursorpath instanceof String && !"".equals(cursorpath)) {
+        Object cursor = Struct.getpath(conn, cursorpath);
+        if (cursor != null) {
+          paging.put("cursor", cursor);
+        }
+      }
+
+      Object morepath = Struct.getprop(page, "more", null);
+      if (morepath instanceof String && !"".equals(morepath)) {
+        Object more = Struct.getpath(conn, morepath);
+        if (more instanceof Boolean) {
+          paging.put("hasMore", more);
+          explicitMore = true;
+        }
+      }
+    }
+
     // Body-level cursors.
     if (body instanceof Map) {
       Map<String, Object> bm = (Map<String, Object>) body;
@@ -127,10 +220,16 @@ public class PagingFeature extends BaseFeature {
       }
       if (bm.get("hasMore") instanceof Boolean) {
         paging.put("hasMore", bm.get("hasMore"));
+        explicitMore = true;
       }
     }
 
-    if (!Boolean.TRUE.equals(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 && !Boolean.TRUE.equals(paging.get("hasMore"))
         && (paging.get("next") != null || paging.get("cursor") != null
             || paging.get("nextPage") != null)) {
       paging.put("hasMore", true);

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

@@ -0,0 +1,191 @@
+package JAVAPACKAGE.utility;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import JAVAPACKAGE.core.Context;
+import JAVAPACKAGE.core.Result;
+import JAVAPACKAGE.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.
+ *
+ * <p>Two jobs:
+ *
+ * <p>graphqlBody — build { query, variables } for a point, binding the op's
+ * arguments to the document's declared variables.
+ *
+ * <p>graphqlErrors — lift a GraphQL failure into an SDK error. GraphQL
+ * reports failures as a top-level {@code errors} array under HTTP 200, so
+ * the status-driven path in resultBasic never sees them.
+ */
+@SuppressWarnings({"unchecked"})
+final class Graphql {
+
+  /** Content type every GraphQL-over-HTTP request uses. */
+  static final String GRAPHQL_CONTENT_TYPE = "application/json";
+
+  private Graphql() {}
+
+  /**
+   * 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 {@code extensions.code};
+   * Linear-style APIs use {@code extensions.type}.
+   */
+  static String graphqlErrorCode(Object gqlerr) {
+    Object ext = Struct.getprop(gqlerr, "extensions", null);
+
+    Object code = Struct.getprop(ext, "code", null);
+    if (null == code || "".equals(code)) {
+      code = Struct.getprop(ext, "type", null);
+    }
+
+    String raw = (code instanceof String) ? ((String) 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";
+    }
+
+    return "request_graphql";
+  }
+
+  /**
+   * Build the request body for a GraphQL point.
+   *
+   * <p>Variables come from the op's own arguments: a named variable binds to
+   * the like-named argument ({@code from}), and the input-object variable
+   * (empty {@code from}) takes the request data as a whole — which is what
+   * makes a generated create/update call look exactly like its REST
+   * equivalent.
+   */
+  static Object graphqlBody(Context ctx) {
+    Object gql = Struct.getprop(ctx.point, "graphql", null);
+
+    if (!(gql instanceof Map)) {
+      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.
+    Map<String, Object> reqsrc = ctx.reqmatch;
+    Map<String, Object> datasrc = ctx.match;
+    if (null != ctx.op && "data".equals(ctx.op.input)) {
+      reqsrc = ctx.reqdata;
+      datasrc = ctx.data;
+    }
+    if (null == reqsrc) {
+      reqsrc = new LinkedHashMap<>();
+    }
+    if (null == datasrc) {
+      datasrc = new LinkedHashMap<>();
+    }
+
+    Map<String, Object> variables = new LinkedHashMap<>();
+
+    Object rawvars = Struct.getprop(gql, "vars", null);
+    List<Object> varlist =
+        (rawvars instanceof List) ? (List<Object>) rawvars : new ArrayList<>();
+
+    for (Object spec : varlist) {
+      if (!(spec instanceof Map)) {
+        continue;
+      }
+
+      Object nameval = Struct.getprop(spec, "name", null);
+      String name = (nameval instanceof String) ? (String) nameval : "";
+
+      Object fromval = Struct.getprop(spec, "from", null);
+      String from = (fromval instanceof String) ? (String) fromval : "";
+
+      if ("".equals(from)) {
+        // The input object IS the request body. Strip the action selector,
+        // which is an SDK-side point discriminator, not an API field.
+        Map<String, Object> body = new LinkedHashMap<>();
+        for (Map.Entry<String, Object> e : reqsrc.entrySet()) {
+          if (!"$action".equals(e.getKey())) {
+            body.put(e.getKey(), e.getValue());
+          }
+        }
+        variables.put(name, body);
+        continue;
+      }
+
+      // Only send variables the caller actually supplied: sending an
+      // explicit null would clear a field on many APIs.
+      Object val = Struct.getprop(reqsrc, from, null);
+      if (null == val) {
+        val = Struct.getprop(datasrc, from, null);
+      }
+      if (null != val) {
+        variables.put(name, val);
+      }
+    }
+
+    Map<String, Object> out = new LinkedHashMap<>();
+    out.put("query", Struct.getprop(gql, "doc", null));
+    out.put("variables", variables);
+
+    return out;
+  }
+
+  /**
+   * Inspect a decoded GraphQL response body and record a failure when the
+   * server reported one. Returns true when an error was recorded.
+   *
+   * <p>Partial data ({@code data} alongside {@code errors}) is treated as
+   * failure: the REST surface has no partial-success concept, and silently
+   * returning half an object would be worse than failing. The raw envelope
+   * stays available on the result for callers that need it.
+   */
+  static Result graphqlErrors(Context ctx) {
+    Result result = ctx.result;
+
+    if (null == result || null == ctx.point) {
+      return result;
+    }
+
+    if (!"graphql".equals(Struct.getprop(ctx.point, "kind", null))) {
+      return result;
+    }
+
+    Object rawerrors = Struct.getprop(result.body, "errors", null);
+    if (!(rawerrors instanceof List)) {
+      return result;
+    }
+
+    List<Object> errors = (List<Object>) rawerrors;
+    if (0 == errors.size()) {
+      return result;
+    }
+
+    Object first = errors.get(0);
+    Object msgval = Struct.getprop(first, "message", null);
+    String msg = (msgval instanceof String) ? (String) msgval : "graphql error";
+    if (1 < errors.size()) {
+      msg = msg + " (+" + (errors.size() - 1) + " more)";
+    }
+
+    result.err = ctx.makeError(graphqlErrorCode(first), "graphql: " + msg);
+    result.ok = false;
+
+    return result;
+  }
+}

package/project/.sdk/tm/java/utility/MakeOptions.java

@@ -73,7 +73,7 @@ final class 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\": {} } },"

package/project/.sdk/tm/java/utility/MakeResponse.java

@@ -39,6 +39,12 @@ final class MakeResponse {
     utility.resultBasic.apply(ctx);
     utility.resultHeaders.apply(ctx);
     utility.resultBody.apply(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.apply(ctx);
+
     utility.transformResponse.apply(ctx);
 
     if (result.err == null) {