@voxgig/sdkgen 1.5.1 → 2.0.0

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

@@ -114,8 +114,24 @@ func makeSpecUtil(_ ctx: Context) throws -> Spec {
   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)
+
+  if "graphql" == gp(ctx.point, "kind").asString {
+    // 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 = VMap()
+    ctx.spec!.headers.entries["content-type"] = .string(graphqlContentType)
+  }
+  else {
+    ctx.spec!.body = utility.prepareBody(ctx)
+    ctx.spec!.path = utility.preparePath(ctx)
+  }
 
   if let explain = ctx.ctrl.explain {
     explain.entries["spec"] = .nat(ctx.spec!)
@@ -266,6 +282,12 @@ func makeResponseUtil(_ ctx: Context) throws -> 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 == nil {

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

@@ -12,7 +12,7 @@ private func buildOptSpec() -> Value {
 
   let allow = VMap()
   allow.entries["method"] = .string("GET,PUT,POST,PATCH,DELETE,OPTIONS")
-  allow.entries["op"] = .string("create,update,load,list,remove,command,direct")
+  allow.entries["op"] = .string("create,update,load,list,remove,command,direct,graphql")
 
   let entityChild = VMap()
   entityChild.entries["`$OPEN`"] = .bool(true)

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

@@ -28,6 +28,8 @@ func registerAll(_ u: Utility) {
   u.prepareParams = prepareParamsUtil
   u.preparePath = preparePathUtil
   u.prepareQuery = prepareQueryUtil
+  u.graphqlBody = graphqlBodyUtil
+  u.graphqlErrors = graphqlErrorsUtil
   u.resultBasic = resultBasicUtil
   u.resultBody = resultBodyUtil
   u.resultHeaders = resultHeadersUtil

package/project/.sdk/tm/ts/src/Point.ts

@@ -4,6 +4,11 @@ import { getprop } from './utility/StructUtility'
 
 class Point {
   args: { params: any[] }
+  // Transport this point speaks: 'http' (default) or 'graphql'. GraphQL
+  // points carry their operation document in `graphql` and address the
+  // single endpoint, so method is always POST and parts is empty.
+  kind: string
+  graphql?: any
   rename: { params: Record<string, string> }
   method: string
   orig: string
@@ -17,6 +22,8 @@ class Point {
 
   constructor(altmap: Record<string, any>) {
     this.args = getprop(altmap, 'args', { params: [] })
+    this.kind = getprop(altmap, 'kind', 'http')
+    this.graphql = getprop(altmap, 'graphql')
     this.rename = getprop(altmap, 'rename', { params: {} })
     this.method = getprop(altmap, 'method', '')
     this.orig = getprop(altmap, 'orig', '')

package/project/.sdk/tm/ts/src/feature/paging/PagingFeature.ts

@@ -48,6 +48,14 @@ class PagingFeature extends BaseFeature {
     // A per-call cursor/page from ctrl takes priority (used by auto-iteration).
     const paging = (ctx.ctrl && 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.
+    const point: any = ctx.point
+    if ('graphql' === (null == point ? undefined : point.kind)) {
+      return this._graphqlPreRequest(ctx, paging)
+    }
+
     if (null != paging.cursor) {
       spec.query[cursorParam] = paging.cursor
     }
@@ -73,6 +81,10 @@ class PagingFeature extends BaseFeature {
     const headers = result.headers || {}
     const body = result.body
 
+    // Set when the response states hasMore outright, rather than leaving it
+    // to be inferred from the presence of a cursor.
+    let explicitMore = false
+
     const paging: any = {
       page: this._num(this._header(headers, 'x-page')),
       totalCount: this._num(this._header(headers, 'x-total-count')),
@@ -91,16 +103,49 @@ class PagingFeature extends BaseFeature {
       }
     }
 
+    // Relay connections carry the cursor in pageInfo, at the path the model
+    // recorded for this op.
+    const point: any = ctx.point
+    const page = null == point ? undefined : (point.graphql || {}).page
+
+    if (null != page && body && 'object' === typeof body) {
+      const struct: any = ctx.utility.struct
+
+      // `connpath` locates the connection object inside the response
+      // envelope (data.<field>); the cursor/more paths are relative to it.
+      const conn = null == page.connpath || '' === page.connpath ? body :
+        (struct.getpath(body, page.connpath) || body)
+
+      const cursor = struct.getpath(conn, page.cursor)
+      const more = struct.getpath(conn, page.more)
+
+      if (null != cursor) { paging.cursor = cursor }
+      if ('boolean' === typeof more) {
+        paging.hasMore = more
+        explicitMore = true
+      }
+    }
+
     // Body-level cursors.
     if (body && 'object' === typeof body) {
       if (null != body.next) { paging.next = paging.next || body.next }
       if (null != body.cursor) { paging.cursor = body.cursor }
       if (null != body.nextCursor) { paging.cursor = body.nextCursor }
-      if ('boolean' === typeof body.hasMore) { paging.hasMore = body.hasMore }
+      if ('boolean' === typeof body.hasMore) {
+        paging.hasMore = body.hasMore
+        explicitMore = true
+      }
     }
 
-    paging.hasMore = paging.hasMore ||
-      null != paging.next || null != paging.cursor || null != paging.nextPage
+    // 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) {
+      paging.hasMore = paging.hasMore ||
+        null != paging.next || null != paging.cursor || null != paging.nextPage
+    }
 
     result.paging = paging
 
@@ -109,6 +154,40 @@ class PagingFeature extends BaseFeature {
   }
 
 
+
+  // Relay pagination: the cursor is the `after` variable (or whatever the
+  // model recorded), and the page size the `first` variable.
+  _graphqlPreRequest(this: any, ctx: any, paging: any) {
+    const spec = ctx.spec
+    const point = ctx.point
+
+    const body = spec.body
+    if (null == body || 'object' !== typeof body) {
+      return
+    }
+
+    const vars = (body.variables = body.variables || {})
+
+    const afterVar = this._options.afterVar || 'after'
+    const firstVar = this._options.firstVar || 'first'
+
+    // Only bind variables the operation actually declares, or the server
+    // rejects the document.
+    const declared: Record<string, boolean> = {}
+    for (const v of ((point.graphql && point.graphql.vars) || [])) {
+      declared[v.name] = true
+    }
+
+    if (null != paging.cursor && declared[afterVar]) {
+      vars[afterVar] = paging.cursor
+    }
+
+    if (null != this._options.limit && null == vars[firstVar] &&
+      declared[firstVar]) {
+      vars[firstVar] = this._options.limit
+    }
+  }
+
   _isList(this: any, ctx: any): boolean {
     const ops = this._options.ops || ['list']
     return ops.indexOf(ctx.op && ctx.op.name) >= 0

package/project/.sdk/tm/ts/src/feature/test/TestFeature.ts

@@ -64,8 +64,20 @@ class TestFeature extends BaseFeature {
         if (null == data || 'string' !== typeof restf) {
           return data
         }
-        const m = restf.match(/^`body\.([^`.]+)`$/)
-        return null == m ? data : { [m[1]]: data }
+        // Rebuild whatever nesting the op's response transform unwraps, so
+        // the mock agrees with the model. Multi-segment on purpose: GraphQL
+        // ops unwrap `body.data.<field>` (and `body.data.<field>.<entity>`
+        // for mutation payloads), not just a single envelope property.
+        const m = restf.match(/^`body\.(.+)`$/)
+        if (null == m) {
+          return data
+        }
+        let out: any = data
+        const segs = m[1].split('.')
+        for (let i = segs.length - 1; 0 <= i; i--) {
+          out = { [segs[i]]: out }
+        }
+        return out
       }
 
       function respond(status: number, data?: any, res?: any) {

package/project/.sdk/tm/ts/src/utility/GraphqlUtility.ts

@@ -0,0 +1,152 @@
+
+import { Context } from '../types'
+
+
+// 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 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`.
+function graphqlErrorCode(gqlerr: any): string {
+  const ext = (null == gqlerr ? undefined : gqlerr.extensions) || {}
+  const raw = String(ext.code || ext.type || '').toUpperCase()
+
+  if (raw.includes('AUTH') || raw.includes('FORBIDDEN') ||
+    raw.includes('UNAUTHENTICATED')) {
+    return 'request_auth'
+  }
+  if (raw.includes('RATELIMIT') || raw.includes('RATE_LIMIT') ||
+    raw.includes('TOO_MANY')) {
+    return 'request_ratelimit'
+  }
+  if (raw.includes('BAD_USER_INPUT') || raw.includes('VALIDATION') ||
+    raw.includes('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.
+function graphqlBody(ctx: Context): any {
+  const utility = ctx.utility
+  const struct = utility.struct
+  const getprop = struct.getprop
+
+  const point: any = ctx.point
+  const gql = null == point ? undefined : point.graphql
+
+  if (null == gql) {
+    return undefined
+  }
+
+  const op: any = ctx.op
+  const input = null == op ? 'match' : op.input
+
+  // reqmatch/reqdata hold the caller's arguments for this operation.
+  const reqsrc = getprop(ctx, 'req' + input) || {}
+  const datasrc = getprop(ctx, input) || {}
+
+  const variables: Record<string, any> = {}
+
+  for (const spec of (gql.vars || [])) {
+    if ('' === spec.from || null == spec.from) {
+      // The input object IS the request body. Strip the action selector,
+      // which is an SDK-side point discriminator, not an API field.
+      const body: Record<string, any> = {}
+      for (const key of Object.keys(reqsrc)) {
+        if ('$action' !== key) {
+          body[key] = reqsrc[key]
+        }
+      }
+      variables[spec.name] = body
+    }
+    else {
+      const val = undefined !== getprop(reqsrc, spec.from) ?
+        getprop(reqsrc, spec.from) : getprop(datasrc, spec.from)
+
+      // Only send variables the caller actually supplied: sending an
+      // explicit null would clear a field on many APIs.
+      if (undefined !== val && null !== val) {
+        variables[spec.name] = val
+      }
+    }
+  }
+
+  return {
+    query: gql.doc,
+    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. The raw envelope stays available on
+// the result for callers that need it.
+function graphqlErrors(ctx: Context): boolean {
+  const result: any = ctx.result
+  const point: any = ctx.point
+
+  if (null == result || null == point || 'graphql' !== point.kind) {
+    return false
+  }
+
+  const body: any = result.body
+  const errors = null == body ? undefined : body.errors
+
+  if (null == errors || !Array.isArray(errors) || 0 === errors.length) {
+    return false
+  }
+
+  const first = errors[0]
+  const msg = (null == first ? undefined : first.message) || 'graphql error'
+  const code = graphqlErrorCode(first)
+
+  const err: any = ctx.error(code,
+    'graphql: ' + msg + (1 < errors.length ?
+      ' (+' + (errors.length - 1) + ' more)' : ''))
+
+  // Keep the full error list reachable for diagnostics.
+  err.graphql = errors
+  result.err = err
+  result.ok = false
+
+  return true
+}
+
+
+export {
+  graphqlBody,
+  graphqlErrors,
+  graphqlErrorCode,
+  GRAPHQL_CONTENT_TYPE,
+}

package/project/.sdk/tm/ts/src/utility/MakeOptionsUtility.ts

@@ -55,7 +55,7 @@ function makeOptions(ctx: Context) {
     },
     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/ts/src/utility/MakeResponseUtility.ts

@@ -13,6 +13,7 @@ async function makeResponse(ctx: Context): Promise<Response | Error> {
   const resultHeaders = utility.resultHeaders
   const resultBody = utility.resultBody
   const transformResponse = utility.transformResponse
+  const graphqlErrors = utility.graphqlErrors
 
   const spec = ctx.spec
   const result = ctx.result
@@ -38,6 +39,12 @@ async function makeResponse(ctx: Context): Promise<Response | Error> {
     resultBasic(ctx)
     resultHeaders(ctx)
     await 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.
+    graphqlErrors(ctx)
+
     transformResponse(ctx)
 
     if (null == result.err) {

package/project/.sdk/tm/ts/src/utility/MakeSpecUtility.ts

@@ -39,8 +39,25 @@ function makeSpec(ctx: Context): Spec | Error {
   ctx.spec.params = prepareParams(ctx)
   ctx.spec.query = prepareQuery(ctx)
   ctx.spec.headers = prepareHeaders(ctx)
-  ctx.spec.body = prepareBody(ctx)
-  ctx.spec.path = preparePath(ctx)
+
+  if ('graphql' === (point as any).kind) {
+    // 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 (create/update), 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 — duplicating the argument, leaking it
+    // into the URL, and failing servers that reject unknown query params.
+    ctx.spec.query = {}
+    ctx.spec.headers['content-type'] = utility.GRAPHQL_CONTENT_TYPE
+  }
+  else {
+    ctx.spec.body = prepareBody(ctx)
+    ctx.spec.path = preparePath(ctx)
+  }
 
   if (ctx.ctrl.explain) {
     ctx.ctrl.explain.spec = ctx.spec

package/project/.sdk/tm/ts/src/utility/Utility.ts

@@ -15,6 +15,7 @@ import { makeResponse } from './MakeResponseUtility'
 import { makeResult } from './MakeResultUtility'
 import { makePoint } from './MakePointUtility'
 import { makeSpec } from './MakeSpecUtility'
+import { graphqlBody, graphqlErrors, GRAPHQL_CONTENT_TYPE } from './GraphqlUtility'
 import { makeUrl } from './MakeUrlUtility'
 import { param } from './ParamUtility'
 import { prepareAuth } from './PrepareAuthUtility'
@@ -50,6 +51,9 @@ class Utility {
   makeResult = makeResult
   makePoint = makePoint
   makeSpec = makeSpec
+  graphqlBody = graphqlBody
+  graphqlErrors = graphqlErrors
+  GRAPHQL_CONTENT_TYPE = GRAPHQL_CONTENT_TYPE
   makeUrl = makeUrl
   param = param
   prepareAuth = prepareAuth

package/project/.sdk/tm/zig/core/utility.zig

@@ -350,7 +350,7 @@ pub fn make_options_util(ctx: *Context) Value {
         .{ "headers", h.jo(&.{.{ "`$CHILD`", h.vstr("`$STRING`") }}) },
         .{ "allow", h.jo(&.{
             .{ "method", h.vstr("GET,PUT,POST,PATCH,DELETE,OPTIONS") },
-            .{ "op", h.vstr("create,update,load,list,remove,command,direct") },
+            .{ "op", h.vstr("create,update,load,list,remove,command,direct,graphql") },
         }) },
         .{ "entity", h.jo(&.{.{ "`$CHILD`", h.jo(&.{
             .{ "`$OPEN`", h.vbool(true) },
@@ -565,8 +565,28 @@ pub fn make_spec_util(ctx: *Context) E!*Spec {
     spec.params = prepare_params_util(ctx);
     spec.query = prepare_query_util(ctx);
     spec.headers = prepare_headers_util(ctx);
-    spec.body = prepare_body_util(ctx);
-    spec.path = prepare_path_util(ctx);
+
+    const kind: []const u8 = switch (h.getp(point, "kind")) {
+        .string => |s| s,
+        else => "",
+    };
+
+    if (std.mem.eql(u8, kind, "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.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.
+        spec.query = h.omap();
+        h.setp(spec.headers, "content-type", h.vstr(GRAPHQL_CONTENT_TYPE));
+    } else {
+        spec.body = prepare_body_util(ctx);
+        spec.path = prepare_path_util(ctx);
+    }
 
     const c = ctx.ctrl;
     if (c.has_explain()) h.setp(c.explain, "spec", spec.to_value());
@@ -721,6 +741,12 @@ pub fn make_response_util(ctx: *Context) E!*Response {
     _ = 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) result.ok = true;
@@ -936,6 +962,175 @@ pub fn prepare_query_util(ctx: *Context) Value {
     return out;
 }
 
+// ============================================================================
+// 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:
+//
+//   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.
+// ============================================================================
+
+// Content type every GraphQL-over-HTTP request uses.
+pub const 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`.
+pub fn graphql_error_code(gqlerr: Value) []const u8 {
+    const ext = h.getp(gqlerr, "extensions");
+
+    var code: []const u8 = switch (h.getp(ext, "code")) {
+        .string => |s| s,
+        else => "",
+    };
+    if (code.len == 0) {
+        code = switch (h.getp(ext, "type")) {
+            .string => |s| s,
+            else => "",
+        };
+    }
+
+    const raw: []const u8 = std.ascii.allocUpperString(h.A(), code) catch "";
+
+    if (std.mem.indexOf(u8, raw, "AUTH") != null or
+        std.mem.indexOf(u8, raw, "FORBIDDEN") != null or
+        std.mem.indexOf(u8, raw, "UNAUTHENTICATED") != null)
+    {
+        return "request_auth";
+    }
+    if (std.mem.indexOf(u8, raw, "RATELIMIT") != null or
+        std.mem.indexOf(u8, raw, "RATE_LIMIT") != null or
+        std.mem.indexOf(u8, raw, "TOO_MANY") != null)
+    {
+        return "request_ratelimit";
+    }
+    if (std.mem.indexOf(u8, raw, "BAD_USER_INPUT") != null or
+        std.mem.indexOf(u8, raw, "VALIDATION") != null or
+        std.mem.indexOf(u8, raw, "INVALID") != null)
+    {
+        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.
+pub fn graphql_body_util(ctx: *Context) Value {
+    const gql = h.getp(ctx.point, "graphql");
+    if (gql != .object) return h.vnull();
+
+    // reqmatch/reqdata hold the caller's arguments for this operation; which
+    // one depends on whether the op takes match or data input.
+    var reqsrc = ctx.reqmatch;
+    var datasrc = ctx.mtch;
+    if (std.mem.eql(u8, ctx.op.input, "data")) {
+        reqsrc = ctx.reqdata;
+        datasrc = ctx.data;
+    }
+    if (reqsrc != .object) reqsrc = h.omap();
+    if (datasrc != .object) datasrc = h.omap();
+
+    const variables = h.omap();
+
+    const varlist = h.getp(gql, "vars");
+    if (varlist == .array) {
+        for (varlist.array.data.items) |spec| {
+            if (spec != .object) continue;
+
+            const name: []const u8 = switch (h.getp(spec, "name")) {
+                .string => |s| s,
+                else => "",
+            };
+            if (name.len == 0) continue;
+
+            const from: []const u8 = switch (h.getp(spec, "from")) {
+                .string => |s| s,
+                else => "",
+            };
+
+            if (from.len == 0) {
+                // The input object IS the request body. Strip the action
+                // selector, which is an SDK-side point discriminator, not
+                // an API field.
+                const body = h.omap();
+                var it = reqsrc.object.iterator();
+                while (it.next()) |kv| {
+                    const key = kv.key_ptr.*;
+                    if (!std.mem.eql(u8, key, "$action")) {
+                        h.setp(body, key, kv.value_ptr.*);
+                    }
+                }
+                h.setp(variables, name, body);
+                continue;
+            }
+
+            // Only send variables the caller actually supplied: sending an
+            // explicit null would clear a field on many APIs.
+            var val = h.getp(reqsrc, from);
+            if (h.is_noval(val) or h.is_null(val)) val = h.getp(datasrc, from);
+            if (!h.is_noval(val) and !h.is_null(val)) {
+                h.setp(variables, name, val);
+            }
+        }
+    }
+
+    const out = h.omap();
+    h.setp(out, "query", h.getp(gql, "doc"));
+    h.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.
+pub fn graphql_errors_util(ctx: *Context) bool {
+    const result = ctx.result orelse return false;
+
+    const kind: []const u8 = switch (h.getp(ctx.point, "kind")) {
+        .string => |s| s,
+        else => "",
+    };
+    if (!std.mem.eql(u8, kind, "graphql")) return false;
+
+    const errors = h.getp(result.body, "errors");
+    if (errors != .array or errors.array.data.items.len == 0) return false;
+
+    const count = errors.array.data.items.len;
+    const first = errors.array.data.items[0];
+
+    var msg: []const u8 = switch (h.getp(first, "message")) {
+        .string => |s| s,
+        else => "",
+    };
+    if (msg.len == 0) msg = "graphql error";
+    if (1 < count) msg = fmt("{s} (+{d} more)", .{ msg, count - 1 });
+
+    result.err = ctx.make_error(graphql_error_code(first), fmt("graphql: {s}", .{msg}));
+    result.ok = false;
+
+    return true;
+}
+
 const HEADER_AUTH = "authorization";
 const OPTION_APIKEY = "apikey";
 const NOT_FOUND = "__NOTFOUND__";