@voxgig/sdkgen 1.5.0 → 2.0.0

package/project/.sdk/tm/c/feature/paging.c

@@ -12,6 +12,7 @@
 
 #include <ctype.h>
 #include <stdlib.h>
+#include <stdio.h>
 #include <string.h>
 
 typedef struct {
@@ -106,6 +107,93 @@ static void paging_init(Feature* f, Context* ctx, voxgig_value* options) {
   pf->active = fopt_bool(options, "active", false);
 }
 
+// The model records connection/cursor/more as dot paths; getpath_c takes a
+// NULL-terminated segment array. Both the copy and the segment array are
+// sized from the path itself: a fixed buffer would silently truncate a long
+// generated path and look up the wrong node, which reads as "no cursor" and
+// stops pagination after one page.
+static voxgig_value* getpath_dotted(voxgig_value* store, const char* path) {
+  if (!path || path[0] == '\0') return store;
+
+  size_t len = strlen(path);
+
+  // Segment count is bounded by dots + 1, so one allocation covers any path.
+  size_t maxseg = 2;
+  for (size_t i = 0; i < len; i++) {
+    if (path[i] == '.') maxseg++;
+  }
+
+  char* buf = (char*)malloc(len + 1);
+  const char** keys = (const char**)malloc(maxseg * sizeof(char*));
+  if (!buf || !keys) {
+    free(buf);
+    free(keys);
+    return voxgig_new_undef();
+  }
+  memcpy(buf, path, len + 1);
+
+  size_t n = 0;
+  char* save = NULL;
+  for (char* tok = strtok_r(buf, ".", &save); tok;
+       tok = strtok_r(NULL, ".", &save)) {
+    keys[n++] = tok;
+  }
+  keys[n] = NULL;
+
+  voxgig_value* out = getpath_c(store, keys);
+
+  // getpath_c does not retain the key strings, so both buffers are ours to
+  // release once the lookup has returned.
+  free(buf);
+  free(keys);
+
+  return out;
+}
+
+// Relay pagination: the cursor is the `after` variable (or whatever the
+// model named it), and the page size is `first`.
+static void paging_graphql_pre_request(PagingFeature* pf, Context* ctx,
+                                       voxgig_value* paging) {
+  voxgig_value* options = pf->options;
+  voxgig_value* body = ctx->spec->body;
+  if (!voxgig_is_map(body)) return;
+
+  voxgig_value* variables = getp(body, "variables");
+  if (!voxgig_is_map(variables)) {
+    variables = voxgig_new_map();
+    setp(body, "variables", variables);
+  }
+
+  const char* after_var = fopt_str(options, "afterVar", "after");
+  const char* first_var = fopt_str(options, "firstVar", "first");
+
+  // Only bind variables the operation actually declares, or the server
+  // rejects the document.
+  bool after_declared = false, first_declared = false;
+  voxgig_value* varlist = getpath2(ctx->point, "graphql", "vars");
+  if (voxgig_is_list(varlist)) {
+    voxgig_list* vl = voxgig_as_list(varlist);
+    for (size_t i = 0; i < vl->len; i++) {
+      voxgig_value* nv = getp(vl->items[i], "name");
+      if (!voxgig_is_string(nv)) continue;
+      const char* n = voxgig_as_string(nv);
+      if (strcmp(n, after_var) == 0) after_declared = true;
+      if (strcmp(n, first_var) == 0) first_declared = true;
+    }
+  }
+
+  voxgig_value* cursor = getp(paging, "cursor");
+  if (after_declared && !v_is_noval(cursor) && !v_is_null(cursor)) {
+    setp(variables, after_var, v_share(cursor));
+  }
+
+  voxgig_value* limit = getp(options, "limit");
+  if (first_declared && !v_is_noval(limit) && !v_is_null(limit) &&
+      v_is_noval(getp(variables, first_var))) {
+    setp(variables, first_var, v_num((double)fopt_int(options, "limit", 0)));
+  }
+}
+
 static void paging_pre_request(PagingFeature* pf, Context* ctx) {
   voxgig_value* options = pf->options;
   if (!pf->active || !is_list_op(options, ctx->op->name)) return;
@@ -124,6 +212,15 @@ static void paging_pre_request(PagingFeature* pf, Context* ctx) {
   // A per-call cursor/page from ctrl takes priority (auto-iteration).
   voxgig_value* paging = ctx->ctrl->paging;
 
+  // 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.
+  voxgig_value* kind = getp(ctx->point, "kind");
+  if (voxgig_is_string(kind) && strcmp(voxgig_as_string(kind), "graphql") == 0) {
+    paging_graphql_pre_request(pf, ctx, paging);
+    return;
+  }
+
   voxgig_value* cursor = getp(paging, "cursor");
   if (!v_is_noval(cursor) && !v_is_null(cursor)) {
     setp(query, cursor_param, cursor);
@@ -165,6 +262,41 @@ static void paging_pre_result(PagingFeature* pf, Context* ctx) {
     }
   }
 
+  // Set when the response states hasMore outright, rather than leaving it to
+  // be inferred from the presence of a cursor.
+  bool explicit_more = false;
+
+  // Relay connections carry the cursor in pageInfo, at the path the model
+  // recorded for this op.
+  voxgig_value* page = getpath2(ctx->point, "graphql", "page");
+  if (voxgig_is_map(page) && voxgig_is_map(body)) {
+    // `connpath` locates the connection object inside the response envelope
+    // (data.<field>); the cursor/more paths are relative to it.
+    voxgig_value* conn = body;
+    voxgig_value* cpv = getp(page, "connpath");
+    if (voxgig_is_string(cpv) && voxgig_as_string(cpv)[0] != '\0') {
+      voxgig_value* sub = getpath_dotted(body, voxgig_as_string(cpv));
+      if (!v_is_noval(sub) && !v_is_null(sub)) conn = sub;
+    }
+
+    voxgig_value* curv = getp(page, "cursor");
+    if (voxgig_is_string(curv) && voxgig_as_string(curv)[0] != '\0') {
+      voxgig_value* cursor = getpath_dotted(conn, voxgig_as_string(curv));
+      if (!v_is_noval(cursor) && !v_is_null(cursor)) {
+        setp(paging, "cursor", v_share(cursor));
+      }
+    }
+
+    voxgig_value* morev = getp(page, "more");
+    if (voxgig_is_string(morev) && voxgig_as_string(morev)[0] != '\0') {
+      voxgig_value* mv = getpath_dotted(conn, voxgig_as_string(morev));
+      if (voxgig_is_bool(mv)) {
+        setp(paging, "hasMore", v_bool(voxgig_as_bool(mv)));
+        explicit_more = true;
+      }
+    }
+  }
+
   // Body-level cursors.
   if (voxgig_is_map(body)) {
     voxgig_value* next = getp(body, "next");
@@ -182,14 +314,21 @@ static void paging_pre_result(PagingFeature* pf, Context* ctx) {
     bool has_more;
     if (get_bool(body, "hasMore", &has_more)) {
       setp(paging, "hasMore", v_bool(has_more));
+      explicit_more = 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.
   bool hm = false;
   bool has = get_bool(paging, "hasMore", &hm);
   bool is_true = has && hm;
-  if (!is_true && (!v_is_noval(getp(paging, "next")) || !v_is_noval(getp(paging, "cursor")) ||
-                   !v_is_noval(getp(paging, "nextPage")))) {
+  if (!explicit_more && !is_true &&
+      (!v_is_noval(getp(paging, "next")) || !v_is_noval(getp(paging, "cursor")) ||
+       !v_is_noval(getp(paging, "nextPage")))) {
     setp(paging, "hasMore", v_bool(true));
   }
 

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

@@ -0,0 +1,178 @@
+// graphql utility (mirrors utility/GraphqlUtility.ts).
+//
+// 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_util   — build { query, variables } for a point, binding
+//                         the op's arguments to the document's declared
+//                         variables.
+//
+//   graphql_errors_util — 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.
+
+#include "sdk.h"
+
+#include <stdio.h>
+#include <string.h>
+#include <ctype.h>
+
+// Uppercase copy, bounded. Used only to normalise an extension code.
+static void upper_copy(const char* src, char* dst, size_t cap) {
+  size_t i = 0;
+  if (src != NULL) {
+    for (; src[i] != '\0' && i + 1 < cap; i++) {
+      dst[i] = (char)toupper((unsigned char)src[i]);
+    }
+  }
+  dst[i] = '\0';
+}
+
+// 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`.
+const char* graphql_error_code(voxgig_value* gqlerr) {
+  voxgig_value* ext = getp(gqlerr, "extensions");
+
+  voxgig_value* code = getp(ext, "code");
+  if (!voxgig_is_string(code)) {
+    code = getp(ext, "type");
+  }
+
+  char raw[128];
+  upper_copy(voxgig_is_string(code) ? voxgig_as_string(code) : "", raw, sizeof(raw));
+
+  if (strstr(raw, "AUTH") || strstr(raw, "FORBIDDEN") ||
+      strstr(raw, "UNAUTHENTICATED")) {
+    return "request_auth";
+  }
+  if (strstr(raw, "RATELIMIT") || strstr(raw, "RATE_LIMIT") ||
+      strstr(raw, "TOO_MANY")) {
+    return "request_ratelimit";
+  }
+  if (strstr(raw, "BAD_USER_INPUT") || strstr(raw, "VALIDATION") ||
+      strstr(raw, "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.
+voxgig_value* graphql_body_util(Context* ctx) {
+  voxgig_value* gql = getp(ctx->point, "graphql");
+  if (!voxgig_is_map(gql)) return voxgig_new_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.
+  voxgig_value* reqsrc = ctx->reqmatch;
+  voxgig_value* datasrc = ctx->mtch;
+  if (ctx->op != NULL && ctx->op->input != NULL &&
+      strcmp(ctx->op->input, "data") == 0) {
+    reqsrc = ctx->reqdata;
+    datasrc = ctx->data;
+  }
+  if (!voxgig_is_map(reqsrc)) reqsrc = voxgig_new_map();
+  if (!voxgig_is_map(datasrc)) datasrc = voxgig_new_map();
+
+  voxgig_value* variables = voxgig_new_map();
+
+  voxgig_value* varlist = getp(gql, "vars");
+  if (voxgig_is_list(varlist)) {
+    voxgig_list* vl = voxgig_as_list(varlist);
+    for (size_t i = 0; i < vl->len; i++) {
+      voxgig_value* spec = vl->items[i];
+      if (!voxgig_is_map(spec)) continue;
+
+      voxgig_value* nameval = getp(spec, "name");
+      if (!voxgig_is_string(nameval)) continue;
+      const char* name = voxgig_as_string(nameval);
+
+      voxgig_value* fromval = getp(spec, "from");
+      const char* from = voxgig_is_string(fromval) ? voxgig_as_string(fromval) : "";
+
+      if (from[0] == '\0') {
+        // The input object IS the request body. Strip the action selector,
+        // which is an SDK-side point discriminator, not an API field.
+        voxgig_value* body = voxgig_new_map();
+        voxgig_map* rm = voxgig_as_map(reqsrc);
+        for (size_t j = 0; j < rm->len; j++) {
+          if (strcmp(rm->entries[j].key, "$action") != 0) {
+            setp(body, rm->entries[j].key, v_share(rm->entries[j].value));
+          }
+        }
+        setp(variables, name, body);
+        continue;
+      }
+
+      // Only send variables the caller actually supplied: sending an
+      // explicit null would clear a field on many APIs.
+      voxgig_value* val = getp(reqsrc, from);
+      if (v_is_noval(val) || v_is_null(val)) {
+        val = getp(datasrc, from);
+      }
+      if (!v_is_noval(val) && !v_is_null(val)) {
+        setp(variables, name, v_share(val));
+      }
+    }
+  }
+
+  voxgig_value* out = voxgig_new_map();
+  setp(out, "query", v_share(getp(gql, "doc")));
+  setp(out, "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.
+//
+// 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. The raw envelope stays available on
+// the result for callers that need it.
+bool graphql_errors_util(Context* ctx) {
+  SdkResult* result = ctx->result;
+  if (result == NULL || ctx->point == NULL) return false;
+
+  voxgig_value* kind = getp(ctx->point, "kind");
+  if (!voxgig_is_string(kind) || strcmp(voxgig_as_string(kind), "graphql") != 0) {
+    return false;
+  }
+
+  voxgig_value* errors = getp(result->body, "errors");
+  if (!voxgig_is_list(errors)) return false;
+
+  voxgig_list* el = voxgig_as_list(errors);
+  if (el->len == 0) return false;
+
+  voxgig_value* first = el->items[0];
+  voxgig_value* msgval = getp(first, "message");
+  const char* msg = voxgig_is_string(msgval) ? voxgig_as_string(msgval) : "graphql error";
+
+  char buf[512];
+  if (el->len > 1) {
+    snprintf(buf, sizeof(buf), "graphql: %s (+%zu more)", msg, el->len - 1);
+  } else {
+    snprintf(buf, sizeof(buf), "graphql: %s", msg);
+  }
+
+  result->err = context_make_error(ctx, graphql_error_code(first), buf);
+  result->ok = false;
+
+  return true;
+}

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

@@ -64,7 +64,7 @@ voxgig_value* make_options_util(Context* ctx) {
     "headers", cmap(1, "`$CHILD`", v_str("`$STRING`")),
     "allow", cmap(2,
       "method", v_str("GET,PUT,POST,PATCH,DELETE,OPTIONS"),
-      "op", v_str("create,update,load,list,remove,command,direct")),
+      "op", v_str("create,update,load,list,remove,command,direct,graphql")),
     "entity", cmap(1, "`$CHILD`", cmap(3,
       "`$OPEN`", v_bool(true),
       "active", v_bool(false),

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

@@ -30,6 +30,12 @@ Response* make_response_util(Context* ctx, PNError** err) {
   result_basic_util(ctx);
   result_headers_util(ctx);
   result_body_util(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.
+  graphql_errors_util(ctx);
+
   transform_response_util(ctx);
 
   if (result->err == NULL) {

package/project/.sdk/tm/c/utility/make_spec.c

@@ -43,9 +43,29 @@ Spec* make_spec_util(Context* ctx, PNError** err) {
   spec->params = prepare_params_util(ctx);
   spec->query = prepare_query_util(ctx);
   spec->headers = prepare_headers_util(ctx);
-  spec->body = prepare_body_util(ctx);
-  char* path = prepare_path_util(ctx);
-  spec_set_path(spec, path);
+
+  voxgig_value* pkind = getp(ctx->point, "kind");
+  bool is_graphql = voxgig_is_string(pkind) &&
+                    strcmp(voxgig_as_string(pkind), "graphql") == 0;
+
+  if (is_graphql) {
+    // GraphQL addresses one endpoint: no path parts, no query string, and
+    // the body carries the operation. prepare_body is skipped deliberately
+    // — it only emits a body for data-input ops, whereas every GraphQL op
+    // posts one, including load/list/remove.
+    spec->body = graphql_body_util(ctx);
+    spec_set_path(spec, "");
+    // prepare_query 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 = voxgig_new_map();
+    setp(spec->headers, "content-type",
+         voxgig_new_string(GRAPHQL_CONTENT_TYPE));
+  } else {
+    spec->body = prepare_body_util(ctx);
+    char* path = prepare_path_util(ctx);
+    spec_set_path(spec, path);
+  }
 
   Control* c = ctx->ctrl;
   if (control_has_explain(c)) {

package/project/.sdk/tm/clojure/src/sdk/client.clj

@@ -83,7 +83,22 @@
       (when fd-err (core/sdk-throw fd-err))
       fetchdef)))
 
-(defn direct [client fetchargs]
+;; Is this raw-access op permitted by the SDK's allow.op option?
+(defn- op-allowed? [client op]
+  (let [allow (vs/getpath (core/client-options-map client) "allow.op")]
+    (and (string? allow) (str/includes? allow op))))
+
+(defn- op-denied [client op]
+  (let [allow (vs/getpath (core/client-options-map client) "allow.op")]
+    (vs/jm "ok" false
+           "err" (str "ProjectNameSDK: " op ": operation not allowed by"
+                      " SDK option allow.op value: \"" (or allow "") "\""))))
+
+;; 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.
+(defn- raw-request [client fetchargs]
   (let [utility (core/client-utility client)
         fetchargs (or fetchargs (vs/jm))
         pr (try {:fd (prepare client fetchargs)}
@@ -109,6 +124,54 @@
             (vs/jm "ok" (and (>= status 200) (< status 300)) "status" status "headers" headers "data" json-data))
           :else (vs/jm "ok" false "err" (core/ctx-error ctx "direct_invalid" "invalid response type")))))))
 
+;; 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.
+(defn direct [client fetchargs]
+  (if (op-allowed? client "direct")
+    (raw-request client fetchargs)
+    (op-denied client "direct")))
+
+;; 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.
+;;
+;; 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 `errors` array, so status alone would report a failed query as
+;; ok.
+;;
+;; NOTE: like direct, this bypasses the feature pipeline — no retry, ratelimit
+;; or paging features apply.
+(defn graphql
+  ([client query] (graphql client query nil nil))
+  ([client query variables] (graphql client query variables nil))
+  ([client query variables ctrl]
+   (if-not (op-allowed? client "graphql")
+     (op-denied client "graphql")
+     (let [res (raw-request client
+                 (vs/jm "method" "POST"
+                        "headers" (vs/jm "content-type" "application/json")
+                        "body" (vs/jm "query" query
+                                      "variables" (or variables (vs/jm)))
+                        "ctrl" (or ctrl (vs/jm))))
+           ;; 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.
+           errors (vs/getpath res "data.errors")
+           n (if (vs/islist errors) (vs/size errors) 0)]
+       (if (zero? n)
+         res
+         (let [m (vs/getprop (vs/getprop errors 0) "message")
+               m (if (and (string? m) (seq m)) m "graphql error")]
+           (.put ^java.util.Map res "ok" false)
+           (.put ^java.util.Map res "err" (str "ProjectNameSDK: graphql: " m))
+           (.put ^java.util.Map res "graphql" errors)
+           res))))))
+
 (defn test-sdk [testopts sdkopts]
   (let [sdkopts (let [c (vs/clone (or sdkopts (vs/jm)))] (if (vs/ismap c) c (vs/jm)))
         testopts (let [c (vs/clone (or testopts (vs/jm)))] (if (vs/ismap c) c (vs/jm)))]

package/project/.sdk/tm/clojure/src/sdk/core.clj

@@ -471,6 +471,108 @@
 (defn u-prepare-body [ctx]
   (if (= "data" (op-input (oget ctx :op))) (ucall ctx :transform-request) nil))
 
+;; ---- graphql ---------------------------------------------------------------
+;;
+;; 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:
+;;
+;;   u-graphql-body   — build {query, variables} for a point, binding the op's
+;;                      arguments to the document's declared variables.
+;;
+;;   u-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.
+
+;; Content type every GraphQL-over-HTTP request uses.
+(def 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`.
+(defn graphql-error-code [gqlerr]
+  (let [ext (vs/getprop gqlerr "extensions")
+        code (let [c (vs/getprop ext "code")]
+               (if (and (string? c) (seq c)) c (vs/getprop ext "type")))
+        raw (str/upper-case (if (string? code) code ""))]
+    (cond
+      (or (str/includes? raw "AUTH") (str/includes? raw "FORBIDDEN")
+          (str/includes? raw "UNAUTHENTICATED")) "request_auth"
+      (or (str/includes? raw "RATELIMIT") (str/includes? raw "RATE_LIMIT")
+          (str/includes? raw "TOO_MANY")) "request_ratelimit"
+      (or (str/includes? raw "BAD_USER_INPUT") (str/includes? raw "VALIDATION")
+          (str/includes? raw "INVALID")) "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.
+(defn u-graphql-body [ctx]
+  (let [gql (vs/getprop (oget ctx :point) "graphql")]
+    (when (vs/ismap gql)
+      ;; reqmatch/reqdata hold the caller's arguments for this operation;
+      ;; which one depends on whether the op takes match or data input.
+      (let [datainput (= "data" (op-input (oget ctx :op)))
+            reqsrc (let [r (if datainput (oget ctx :reqdata) (oget ctx :reqmatch))]
+                     (if (vs/ismap r) r (vs/jm)))
+            ;; data/match hold the entity's current state; a named variable
+            ;; falls back to it, so updating a loaded entity with just
+            ;; {title} still binds the stored id the mutation requires.
+            datasrc (let [d (if datainput (oget ctx :data) (oget ctx :match))]
+                      (if (vs/ismap d) d (vs/jm)))
+            variables (vs/jm)
+            varlist (let [v (vs/getprop gql "vars")] (if (vs/islist v) v (vs/jt)))]
+        (doseq [spec (vec varlist)]
+          (when (vs/ismap spec)
+            (let [name (vs/getprop spec "name")
+                  from (vs/getprop spec "from")]
+              (when (and (string? name) (seq name))
+                (if (or (nil? from) (not (string? from)) (empty? from))
+                  ;; The input object IS the request body. Strip the action
+                  ;; selector, which is an SDK-side point discriminator, not
+                  ;; an API field.
+                  (let [body (vs/jm)]
+                    (doseq [item (or (vs/items reqsrc) [])]
+                      (let [k (vs/getprop item 0) v (vs/getprop item 1)]
+                        (when (not= "$action" k) (.put ^java.util.Map body k v))))
+                    (.put ^java.util.Map variables name body))
+                  ;; Only send variables the caller actually supplied: sending
+                  ;; an explicit null would clear a field on many APIs.
+                  (let [val (let [v (vs/getprop reqsrc from)]
+                              (if (some? v) v (vs/getprop datasrc from)))]
+                    (when (some? val) (.put ^java.util.Map variables name val))))))))
+        (vs/jm "query" (vs/getprop gql "doc") "variables" 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.
+(defn u-graphql-errors [ctx]
+  (let [result (oget ctx :result)
+        errors (when result (vs/getprop (oget result :body) "errors"))
+        n (if (vs/islist errors) (vs/size errors) 0)]
+    (if (or (nil? result)
+            (not= "graphql" (vs/getprop (oget ctx :point) "kind"))
+            (zero? n))
+      false
+      (let [first-err (vs/getprop errors 0)
+            m (vs/getprop first-err "message")
+            m (if (and (string? m) (seq m)) m "graphql error")
+            m (if (< 1 n) (str m " (+" (dec n) " more)") m)]
+        (oset! result :err (ctx-error ctx (graphql-error-code first-err) (str "graphql: " m)))
+        (oset! result :ok false)
+        true))))
+
 (def HEADER-AUTH "authorization")
 (def OPTION-APIKEY "apikey")
 (def NOT-FOUND "__NOTFOUND__")
@@ -566,8 +668,23 @@
             (oset! spec :params (ucall ctx :prepare-params))
             (oset! spec :query (ucall ctx :prepare-query))
             (oset! spec :headers (ucall ctx :prepare-headers))
-            (oset! spec :body (ucall ctx :prepare-body))
-            (oset! spec :path (ucall ctx :prepare-path))
+            (if (= "graphql" (vs/getprop point "kind"))
+              ;; GraphQL addresses one endpoint: no path parts, no query
+              ;; string, and the body carries the operation. prepare-body is
+              ;; skipped deliberately — it only emits a body for data-input
+              ;; ops, whereas every GraphQL op posts one, including
+              ;; load/list/remove.
+              (do
+                (oset! spec :body (ucall ctx :graphql-body))
+                (oset! spec :path "")
+                ;; prepare-query 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.
+                (oset! spec :query (vs/jm))
+                (.put ^java.util.Map (oget spec :headers) "content-type" GRAPHQL-CONTENT-TYPE))
+              (do
+                (oset! spec :body (ucall ctx :prepare-body))
+                (oset! spec :path (ucall ctx :prepare-path))))
             (when-let [ex (oget (oget ctx :ctrl) :explain)] (.put ^java.util.Map ex "spec" spec))
             (let [[s err] (ucall ctx :prepare-auth)]
               (if err [nil err] (do (oset! ctx :spec s) [s nil])))))))))
@@ -696,6 +813,11 @@
             (ucall ctx :result-basic)
             (ucall ctx :result-headers)
             (ucall ctx :result-body)
+            ;; 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.
+            (ucall ctx :graphql-errors)
             (ucall ctx :transform-response)
             (when (nil? (oget result :err)) (oset! result :ok true))
             (when-let [ex (oget (oget ctx :ctrl) :explain)] (.put ^java.util.Map ex "result" result))
@@ -800,7 +922,7 @@
                    "auth" (vs/jm "prefix" "")
                    "headers" (vs/jm "`$CHILD`" "`$STRING`")
                    "allow" (vs/jm "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" (vs/jm "`$CHILD`" (vs/jm "`$OPEN`" true "active" false "alias" (vs/jm)))
                    "feature" (vs/jm "`$CHILD`" (vs/jm "`$OPEN`" true "active" false))
                    "utility" (vs/jm)
@@ -901,6 +1023,7 @@
    :param u-param :prepare-auth u-prepare-auth :prepare-body u-prepare-body
    :prepare-headers u-prepare-headers :prepare-method u-prepare-method :prepare-params u-prepare-params
    :prepare-path u-prepare-path :prepare-query u-prepare-query
+   :graphql-body u-graphql-body :graphql-errors u-graphql-errors
    :result-basic u-result-basic :result-body u-result-body :result-headers u-result-headers
    :transform-request u-transform-request :transform-response u-transform-response})