@voxgig/sdkgen 1.5.0 → 2.0.0

package/project/.sdk/tm/csharp/feature/PagingFeature.cs

@@ -10,6 +10,8 @@
 
 using System.Text.RegularExpressions;
 
+using Voxgig.Struct;
+
 using static ProjectNameSdk.Feature.FeatureOptions;
 
 namespace ProjectNameSdk.Feature;
@@ -59,6 +61,16 @@ public class PagingFeature : BaseFeature
         // A per-call cursor/page from ctrl takes priority (auto-iteration).
         var paging = ctx.Ctrl?.Paging;
 
+        // GraphQL paginates through operation VARIABLES, not the query
+        // string. This hook runs after MakeSpec, so spec.Body already holds
+        // the { query, variables } envelope, and before MakeFetchDef
+        // serialises it.
+        if ("graphql" == StructUtils.GetProp(ctx.Point, "kind") as string)
+        {
+            GraphqlPreRequest(ctx, paging);
+            return;
+        }
+
         object? cursor = null;
         var hasCursor = paging != null && paging.TryGetValue("cursor", out cursor) && cursor != null;
         if (hasCursor)
@@ -79,6 +91,60 @@ public class PagingFeature : BaseFeature
         }
     }
 
+    // Relay pagination: the cursor is the `after` variable (or whatever the
+    // model named it), and the page size is `first`.
+    private void GraphqlPreRequest(Context ctx, Dictionary<string, object?>? paging)
+    {
+        if (ctx.Spec?.Body is not Dictionary<string, object?> body)
+        {
+            return;
+        }
+
+        if (body.TryGetValue("variables", out var vv) &&
+            vv is Dictionary<string, object?> existing)
+        {
+            // reuse
+            vv = existing;
+        }
+        else
+        {
+            vv = new Dictionary<string, object?>();
+            body["variables"] = vv;
+        }
+        var variables = (Dictionary<string, object?>)vv;
+
+        var afterVar = FoptStr(_options, "afterVar", "after");
+        var firstVar = FoptStr(_options, "firstVar", "first");
+
+        // Only bind variables the operation actually declares, or the server
+        // rejects the document.
+        var declared = new HashSet<string>();
+        if (StructUtils.GetPath(ctx.Point, StructUtils.Jt("graphql", "vars"))
+            is List<object?> varlist)
+        {
+            foreach (var v in varlist)
+            {
+                if (StructUtils.GetProp(v, "name") is string name)
+                {
+                    declared.Add(name);
+                }
+            }
+        }
+
+        object? cursor = null;
+        if (paging != null && paging.TryGetValue("cursor", out cursor) &&
+            cursor != null && declared.Contains(afterVar))
+        {
+            variables[afterVar] = cursor;
+        }
+
+        if (Opt(_options, "limit") != null && declared.Contains(firstVar) &&
+            (!variables.TryGetValue(firstVar, out var fv) || fv == null))
+        {
+            variables[firstVar] = FoptInt(_options, "limit", 0);
+        }
+    }
+
     public override void PreResult(Context ctx)
     {
         if (!Active || !IsList(ctx))
@@ -113,6 +179,51 @@ public class PagingFeature : BaseFeature
             }
         }
 
+        // Set when the response states hasMore outright, rather than leaving
+        // it to be inferred from the presence of a cursor.
+        var explicitMore = false;
+
+        // Relay connections carry the cursor in pageInfo, at the path the
+        // model recorded for this op.
+        if (StructUtils.GetPath(ctx.Point, StructUtils.Jt("graphql", "page"))
+                is Dictionary<string, object?> page
+            && body is Dictionary<string, object?>)
+        {
+            // `connpath` locates the connection object inside the response
+            // envelope (data.<field>); the cursor/more paths are relative
+            // to it.
+            object? conn = body;
+            if (page.TryGetValue("connpath", out var cpv) &&
+                cpv is string connpath && "" != connpath)
+            {
+                var sub = StructUtils.GetPath(body, connpath);
+                if (sub != null)
+                {
+                    conn = sub;
+                }
+            }
+
+            if (page.TryGetValue("cursor", out var curv) &&
+                curv is string cursorpath && "" != cursorpath)
+            {
+                var c = StructUtils.GetPath(conn, cursorpath);
+                if (c != null)
+                {
+                    paging["cursor"] = c;
+                }
+            }
+
+            if (page.TryGetValue("more", out var mv) &&
+                mv is string morepath && "" != morepath)
+            {
+                if (StructUtils.GetPath(conn, morepath) is bool more)
+                {
+                    paging["hasMore"] = more;
+                    explicitMore = true;
+                }
+            }
+        }
+
         // Body-level cursors.
         if (body is Dictionary<string, object?> bm)
         {
@@ -132,10 +243,16 @@ public class PagingFeature : BaseFeature
             if (bm.TryGetValue("hasMore", out var hasMore) && hasMore is bool hmb)
             {
                 paging["hasMore"] = hmb;
+                explicitMore = true;
             }
         }
 
-        if (!Equals(paging["hasMore"], 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.
+        if (!explicitMore && !Equals(paging["hasMore"], true) &&
             ((paging.TryGetValue("next", out var n2) && n2 != null) ||
              (paging.TryGetValue("cursor", out var c2) && c2 != null) ||
              (paging.TryGetValue("nextPage", out var np2) && np2 != null)))

package/project/.sdk/tm/csharp/utility/Graphql.cs

@@ -0,0 +1,190 @@
+// 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:
+//
+//   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.
+
+using Voxgig.Struct;
+
+namespace ProjectNameSdk.Util;
+
+public static partial class SdkUtility
+{
+    // Content type every GraphQL-over-HTTP request uses.
+    internal const 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`.
+    internal static string GraphqlErrorCode(object? gqlerr)
+    {
+        var ext = StructUtils.GetProp(gqlerr, "extensions");
+
+        var code = StructUtils.GetProp(ext, "code") as string;
+        if (string.IsNullOrEmpty(code))
+        {
+            code = StructUtils.GetProp(ext, "type") as string;
+        }
+
+        var raw = (code ?? "").ToUpperInvariant();
+
+        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.
+    internal static object? GraphqlBodyUtil(Context ctx)
+    {
+        var gql = StructUtils.GetProp(ctx.Point, "graphql")
+            as Dictionary<string, object?>;
+        if (null == gql)
+        {
+            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.
+        var reqsrc = ctx.Reqmatch;
+        var datasrc = ctx.Match;
+        if (null != ctx.Op && "data" == ctx.Op.Input)
+        {
+            reqsrc = ctx.Reqdata;
+            datasrc = ctx.Data;
+        }
+        reqsrc ??= new Dictionary<string, object?>();
+        datasrc ??= new Dictionary<string, object?>();
+
+        var variables = new Dictionary<string, object?>();
+
+        var varlist = StructUtils.GetProp(gql, "vars") as List<object?>;
+        if (null != varlist)
+        {
+            foreach (var entry in varlist)
+            {
+                if (entry is not Dictionary<string, object?> spec)
+                {
+                    continue;
+                }
+
+                var name = StructUtils.GetProp(spec, "name") as string;
+                if (null == name)
+                {
+                    continue;
+                }
+
+                var from = StructUtils.GetProp(spec, "from") as string;
+
+                if (string.IsNullOrEmpty(from))
+                {
+                    // The input object IS the request body. Strip the
+                    // action selector, which is an SDK-side point
+                    // discriminator, not an API field.
+                    var body = new Dictionary<string, object?>();
+                    foreach (var kv in reqsrc)
+                    {
+                        if ("$action" != kv.Key)
+                        {
+                            body[kv.Key] = kv.Value;
+                        }
+                    }
+                    variables[name] = body;
+                    continue;
+                }
+
+                // Only send variables the caller actually supplied: sending
+                // an explicit null would clear a field on many APIs.
+                var val = StructUtils.GetProp(reqsrc, from)
+                    ?? StructUtils.GetProp(datasrc, from);
+                if (null != val)
+                {
+                    variables[name] = val;
+                }
+            }
+        }
+
+        return new Dictionary<string, object?>
+        {
+            ["query"] = StructUtils.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.
+    internal static bool GraphqlErrorsUtil(Context ctx)
+    {
+        var result = ctx.Result;
+
+        if (null == result || null == ctx.Point)
+        {
+            return false;
+        }
+
+        if ("graphql" != StructUtils.GetProp(ctx.Point, "kind") as string)
+        {
+            return false;
+        }
+
+        if (StructUtils.GetProp(result.Body, "errors") is not List<object?> errors
+            || 0 == errors.Count)
+        {
+            return false;
+        }
+
+        var first = errors[0];
+        var msg = StructUtils.GetProp(first, "message") as string;
+        if (string.IsNullOrEmpty(msg))
+        {
+            msg = "graphql error";
+        }
+        if (1 < errors.Count)
+        {
+            msg = msg + " (+" + (errors.Count - 1) + " more)";
+        }
+
+        result.Err = ctx.MakeError(GraphqlErrorCode(first), "graphql: " + msg);
+        result.Ok = false;
+
+        return true;
+    }
+}

package/project/.sdk/tm/csharp/utility/MakeOptions.cs

@@ -76,7 +76,7 @@ public static partial class SdkUtility
             ["allow"] = new Dictionary<string, object?>
             {
                 ["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"] = new Dictionary<string, object?>
             {

package/project/.sdk/tm/csharp/utility/MakeResponse.cs

@@ -38,6 +38,13 @@ public static partial class SdkUtility
         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/csharp/utility/MakeSpec.cs

@@ -48,8 +48,27 @@ public static partial class SdkUtility
         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" == StructUtils.GetProp(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.
+            ctx.Spec.Body = utility.GraphqlBody(ctx);
+            ctx.Spec.Path = "";
+            // PrepareQuery already copied the op's match arguments into the
+            // query string. Those same values are bound as operation
+            // variables, so leaving them would send /graphql?id=i1.
+            ctx.Spec.Query = new Dictionary<string, object?>();
+            ctx.Spec.Headers["content-type"] = GraphqlContentType;
+        }
+        else
+        {
+            ctx.Spec.Body = utility.PrepareBody(ctx);
+            ctx.Spec.Path = utility.PreparePath(ctx);
+        }
 
         if (ctx.Ctrl.Explain != null)
         {

package/project/.sdk/tm/csharp/utility/Register.cs

@@ -32,6 +32,8 @@ public static partial class SdkUtility
         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/dart/lib/Point.dart

@@ -2,6 +2,11 @@ import 'utility/voxgig_struct.dart' as vs;
 
 class Point {
   dynamic args;
+  // 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.
+  dynamic kind;
+  dynamic graphql;
   dynamic rename;
   dynamic method;
   dynamic orig;
@@ -15,6 +20,8 @@ class Point {
 
   Point(dynamic altmap) {
     args = vs.getprop(altmap, 'args', {'params': []});
+    kind = vs.getprop(altmap, 'kind', 'http');
+    graphql = vs.getprop(altmap, 'graphql');
     rename = vs.getprop(altmap, 'rename', {'params': {}});
     method = vs.getprop(altmap, 'method', '');
     orig = vs.getprop(altmap, 'orig', '');

package/project/.sdk/tm/dart/lib/feature/paging/PagingFeature.dart

@@ -1,5 +1,7 @@
 // ignore_for_file: non_constant_identifier_names
 
+import '../../utility/voxgig_struct.dart' as vs;
+
 import '../base/BaseFeature.dart';
 
 // Pagination support for list operations. On the way out (PreRequest) it
@@ -45,6 +47,14 @@ class PagingFeature extends BaseFeature {
     // A per-call cursor/page from ctrl takes priority (used by auto-iteration).
     final paging = (ctx.ctrl is Map ? ctx.ctrl['paging'] : null) ?? {};
 
+    // 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' == ctx.point?.kind) {
+      _graphqlPreRequest(ctx, paging);
+      return null;
+    }
+
     if (null != paging['cursor']) {
       spec.query[cursorParam] = paging['cursor'];
     } else if (null == spec.query[pageParam]) {
@@ -58,6 +68,46 @@ class PagingFeature extends BaseFeature {
     return null;
   }
 
+  // Relay pagination: the cursor is the `after` variable (or whatever the
+  // model named it), and the page size is `first`.
+  void _graphqlPreRequest(dynamic ctx, dynamic paging) {
+    final body = ctx.spec.body;
+    if (body is! Map) {
+      return;
+    }
+
+    var variables = body['variables'];
+    if (variables is! Map) {
+      variables = <String, dynamic>{};
+      body['variables'] = variables;
+    }
+
+    final afterVar = options['afterVar'] ?? 'after';
+    final firstVar = options['firstVar'] ?? 'first';
+
+    // Only bind variables the operation actually declares, or the server
+    // rejects the document.
+    final declared = <String>{};
+    final varlist = vs.getprop(ctx.point?.graphql, 'vars');
+    if (varlist is List) {
+      for (final v in varlist) {
+        final name = vs.getprop(v, 'name');
+        if (null != name) {
+          declared.add(name.toString());
+        }
+      }
+    }
+
+    if (null != paging['cursor'] && declared.contains(afterVar)) {
+      variables[afterVar] = paging['cursor'];
+    }
+
+    if (null != options['limit'] && null == variables[firstVar] &&
+        declared.contains(firstVar)) {
+      variables[firstVar] = options['limit'];
+    }
+  }
+
   @override
   dynamic PreResult(dynamic ctx) {
     if (!_isList(ctx)) {
@@ -90,6 +140,43 @@ class PagingFeature extends BaseFeature {
       }
     }
 
+    // Set when the response states hasMore outright, rather than leaving it
+    // to be inferred from the presence of a cursor.
+    var explicitMore = false;
+
+    // Relay connections carry the cursor in pageInfo, at the path the model
+    // recorded for this op.
+    final page = vs.getprop(ctx.point?.graphql, 'page');
+    if (page is Map && body is Map) {
+      // `connpath` locates the connection object inside the response
+      // envelope (data.<field>); the cursor/more paths are relative to it.
+      var conn = body;
+      final connpath = page['connpath'];
+      if (connpath is String && '' != connpath) {
+        final sub = vs.getpath(body, connpath);
+        if (sub is Map) {
+          conn = sub;
+        }
+      }
+
+      final cursorpath = page['cursor'];
+      if (cursorpath is String && '' != cursorpath) {
+        final cursor = vs.getpath(conn, cursorpath);
+        if (null != cursor) {
+          paging['cursor'] = cursor;
+        }
+      }
+
+      final morepath = page['more'];
+      if (morepath is String && '' != morepath) {
+        final more = vs.getpath(conn, morepath);
+        if (more is bool) {
+          paging['hasMore'] = more;
+          explicitMore = true;
+        }
+      }
+    }
+
     // Body-level cursors.
     if (body is Map) {
       if (null != body['next']) {
@@ -103,13 +190,21 @@ class PagingFeature extends BaseFeature {
       }
       if (body['hasMore'] is bool) {
         paging['hasMore'] = body['hasMore'];
+        explicitMore = true;
       }
     }
 
-    paging['hasMore'] = true == 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'] = true == paging['hasMore'] ||
+          null != paging['next'] ||
+          null != paging['cursor'] ||
+          null != paging['nextPage'];
+    }
 
     result.paging = paging;