@voxgig/sdkgen 1.5.0 → 2.0.0

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

@@ -97,6 +97,19 @@ pub const PagingFeature = struct {
         // A per-call cursor/page from ctrl takes priority (auto-iteration).
         const 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.
+        const kind: []const u8 = switch (h.getp(ctx.point, "kind")) {
+            .string => |k| k,
+            else => "",
+        };
+        if (std.mem.eql(u8, kind, "graphql")) {
+            self.graphql_pre_request(ctx, paging);
+            return;
+        }
+
         const cursor = h.getp(paging, "cursor");
         if (!h.is_noval(cursor)) {
             h.setp(query, cursor_param, cursor);
@@ -114,6 +127,80 @@ pub const PagingFeature = struct {
         }
     }
 
+    // Relay pagination: the cursor is the `after` variable (or whatever the
+    // model named it), and the page size is `first`.
+    fn graphql_pre_request(self: *PagingFeature, ctx: *Context, paging: Value) void {
+        const sp = ctx.spec orelse return;
+        if (sp.body != .object) return;
+
+        const variables: Value = if (h.getp(sp.body, "variables") == .object)
+            h.getp(sp.body, "variables")
+        else blk: {
+            const nv = h.omap();
+            h.setp(sp.body, "variables", nv);
+            break :blk nv;
+        };
+
+        const after_var = sup.fopt_str(self.options, "afterVar", "after");
+        const first_var = sup.fopt_str(self.options, "firstVar", "first");
+
+        // Only bind variables the operation actually declares, or the server
+        // rejects the document.
+        var after_declared = false;
+        var first_declared = false;
+        const varlist = h.getpath(&.{ "graphql", "vars" }, ctx.point);
+        if (varlist == .array) {
+            for (varlist.array.data.items) |v| {
+                const name: []const u8 = switch (h.getp(v, "name")) {
+                    .string => |n| n,
+                    else => continue,
+                };
+                if (std.mem.eql(u8, name, after_var)) after_declared = true;
+                if (std.mem.eql(u8, name, first_var)) first_declared = true;
+            }
+        }
+
+        const cursor = h.getp(paging, "cursor");
+        if (after_declared and !h.is_noval(cursor) and !h.is_null(cursor)) {
+            h.setp(variables, after_var, cursor);
+        }
+
+        // `limit: null` reads as unset, matching the reference's `null !=
+        // limit`: fopt_int would otherwise coerce it to 0 and bind `first: 0`,
+        // which relay servers reject or answer with an empty page.
+        const limit = h.getp(self.options, "limit");
+        if (first_declared and !h.is_noval(limit) and !h.is_null(limit) and
+            h.is_noval(h.getp(variables, first_var)))
+        {
+            h.setp(variables, first_var, h.vnum(sup.fopt_int(self.options, "limit", 0)));
+        }
+    }
+
+    // The model records connection/cursor/more as dot paths; core getpath
+    // takes pre-split segments.
+    fn getpath_dotted(path: []const u8, store: Value) Value {
+        // Segment count is bounded by dots + 1, so one pass sizes the slice
+        // exactly. A fixed array would silently stop splitting and look up a
+        // truncated path, which reads as "no cursor" — indistinguishable from
+        // a genuine end of pagination. splitScalar yields slices into `path`,
+        // so unlike the C port there is nothing to copy.
+        var nseg: usize = 1;
+        for (path) |c| {
+            if (c == '.') nseg += 1;
+        }
+
+        const segs = h.A().alloc([]const u8, nseg) catch return h.vnull();
+
+        var n: usize = 0;
+        var it = std.mem.splitScalar(u8, path, '.');
+        while (it.next()) |seg| {
+            segs[n] = seg;
+            n += 1;
+        }
+
+        return h.getpath(segs[0..n], store);
+    }
+
     fn pre_result(self: *PagingFeature, ctx: *Context) void {
         if (!self.active or !self.is_list(ctx)) return;
         const result = ctx.result orelse return;
@@ -136,6 +223,40 @@ pub const PagingFeature = struct {
             }
         }
 
+        // Set when the response states hasMore outright, rather than leaving
+        // it to be inferred from the presence of a cursor.
+        var explicit_more = false;
+
+        // Relay connections carry the cursor in pageInfo, at the path the
+        // model recorded for this op.
+        const page = h.getpath(&.{ "graphql", "page" }, ctx.point);
+        if (page == .object and body == .object) {
+            // `connpath` locates the connection object inside the response
+            // envelope (data.<field>); the cursor/more paths are relative
+            // to it.
+            var conn = body;
+            const connpath = h.get_str(page, "connpath") orelse "";
+            if (connpath.len != 0) {
+                const sub = getpath_dotted(connpath, body);
+                if (!h.is_noval(sub) and !h.is_null(sub)) conn = sub;
+            }
+
+            const cursorpath = h.get_str(page, "cursor") orelse "";
+            if (cursorpath.len != 0) {
+                const c = getpath_dotted(cursorpath, conn);
+                if (!h.is_noval(c) and !h.is_null(c)) h.setp(paging, "cursor", c);
+            }
+
+            const morepath = h.get_str(page, "more") orelse "";
+            if (morepath.len != 0) {
+                const mv = getpath_dotted(morepath, conn);
+                if (mv == .bool) {
+                    h.setp(paging, "hasMore", h.vbool(mv.bool));
+                    explicit_more = true;
+                }
+            }
+        }
+
         // Body-level cursors.
         if (body == .object) {
             const next = h.getp(body, "next");
@@ -152,10 +273,16 @@ pub const PagingFeature = struct {
             }
             if (h.get_bool(body, "hasMore")) |has_more| {
                 h.setp(paging, "hasMore", h.vbool(has_more));
+                explicit_more = true;
             }
         }
 
-        if ((h.get_bool(paging, "hasMore") orelse false) != true and
+        // 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 (!explicit_more and (h.get_bool(paging, "hasMore") orelse false) != true and
             (!h.is_noval(h.getp(paging, "next")) or
             !h.is_noval(h.getp(paging, "cursor")) or
             !h.is_noval(h.getp(paging, "nextPage"))))

package/src/cmp/AgentGuideContent.ts

@@ -33,6 +33,11 @@ const LANG_CMD: Record<string, LangCmd> = {
   lua: { install: 'luarocks make', viaMake: true },
   'go-cli': { build: 'go build ./...', note: 'A CLI surface, not an SDK client library.' },
   'go-mcp': { build: 'go build ./...', note: 'An MCP server surface for AI agents, not an SDK client library.' },
+  'py-data': {
+    install: 'make dev',
+    viaMake: true,
+    note: 'A pandas/notebook surface layered on the sibling Python SDK, not an SDK client library.',
+  },
 }
 
 

package/src/cmp/Feature.ts

@@ -11,6 +11,19 @@ const Feature = cmp(function Feature(props: any) {
       Copy({
         from: 'tm/' + target.name + '/src/feature/' + feature.name,
         replace: {
+          // Feature templates reference the SDK class by placeholder — e.g.
+          // tm/ts/.../TestFeature.ts imports `ProjectNameSDK`. Without the
+          // standard replacements those placeholders reach the generated
+          // source verbatim and the target fails to COMPILE.
+          //
+          // This worked by accident everywhere it worked: Main_<lang> copies
+          // the whole tm/<lang> tree (feature dirs included) with stdrep
+          // afterwards, so the substituted version overwrote this one. Any
+          // target whose Main excludes src/ — or any consumer .sdk whose
+          // local Main_<lang> lost that Copy — got the raw placeholder.
+          // voxgig-solardemo-sdk hit exactly that and could not build its
+          // TypeScript at all.
+          ...ctx$.stdrep,
           FEATURE_VERSION: feature.version,
           FEATURE_Name: feature.Name,
         }

package/src/helpers/canonType.ts

@@ -128,6 +128,50 @@ const CANON_UNION_JOIN: Partial<Record<CanonLang, string>> = {
 }
 
 
+// Canonical sentinel -> pandas dtype, for the `py-data` target's generated
+// DataFrame accessors. Deliberately NOT a CanonLang column: py-data is a
+// consumer target layered on `py`, not a language, and these are storage
+// dtypes rather than type-annotation names.
+//
+// NULLABLE dtypes throughout ('Int64' not 'int64', 'boolean' not 'bool').
+// The model carries no nullability beyond the `req` flag, and API payloads
+// omit optional fields freely, so a column that looks integral in one page
+// can arrive with nulls in the next. NumPy's int64/bool cannot hold NA and
+// would silently upcast to float64/object mid-fetch, changing a column's
+// dtype based on which rows came back — the pandas nullable extension types
+// keep it stable.
+//
+// There is no $DATE / $DATETIME sentinel in apidef's vocabulary (the model
+// carries no string formats), so date handling is NOT inferred here. It is
+// an explicit runtime opt-in via the accessor's `parse_dates=` kwarg. Do not
+// add a DATE row unless apidef starts emitting the sentinel.
+const PANDAS_DTYPE: Record<string, string> = {
+  STRING: 'string',
+  INTEGER: 'Int64',
+  NUMBER: 'Float64',
+  BOOLEAN: 'boolean',
+  // A null-typed column has no values to hold; object is the honest floor.
+  NULL: 'object',
+  // Arrays and objects stay boxed Python values in an object column. Frames
+  // flatten one level of OBJECT into dotted columns before dtypes are
+  // applied (see frames.py), so an OBJECT column reaching here is one that
+  // survived flattening — genuinely nested, genuinely object.
+  ARRAY: 'object',
+  OBJECT: 'object',
+  ANY: 'object',
+}
+
+// Map a field type sentinel to a pandas dtype string. Unknown / missing /
+// union ($ONE) sentinels fall back to 'object' — a union column can hold
+// members of different dtypes, so object is the only correct storage.
+function canonToDtype(sentinel: unknown): string {
+  if (Array.isArray(sentinel)) {
+    return 'object'
+  }
+  return PANDAS_DTYPE[canonKey(sentinel)] ?? 'object'
+}
+
+
 // Normalize a raw sentinel value to its bare upper-case key:
 // '`$STRING`' / '$STRING' / 'string' -> 'STRING'.
 function canonKey(sentinel: unknown): string {
@@ -174,10 +218,12 @@ function canonToType(sentinel: unknown, lang: string): string {
 
 export {
   canonToType,
+  canonToDtype,
   canonKey,
   CANON_TYPE,
   CANON_ANY,
   CANON_UNION_JOIN,
+  PANDAS_DTYPE,
 }
 
 export type {

package/src/helpers/packageMeta.ts

@@ -31,6 +31,7 @@ const LANG_LABEL: Record<string, string> = {
   go: 'Go',
   'go-cli': 'Go CLI',
   'go-mcp': 'Go MCP server',
+  'py-data': 'Python Data',
 }
 
 function langLabel(target: string): string {
@@ -151,6 +152,10 @@ function packageName(model: any, eco: string): string {
       return `github.com/${origin}/${slug}-sdk/go-cli`
     case 'go-mcp':
       return `github.com/${origin}/${slug}-sdk/go-mcp`
+    // The notebook/analyst package layered on `py`. Distinct PyPI name so it
+    // can version and publish independently of the SDK it wraps.
+    case 'py-data':
+      return `${origin}-${base}-data`
     default:
       return `${origin}-${base}`
   }
@@ -172,6 +177,8 @@ function installCommand(model: any, target: string): string {
       return `npm install ${packageName(model, 'js')}`
     case 'py':
       return `pip install ${packageName(model, 'pypi')}`
+    case 'py-data':
+      return `pip install ${packageName(model, 'py-data')}`
     case 'php':
       return `composer require ${packageName(model, 'composer')}`
     case 'rb':

package/src/sdkgen.ts

@@ -50,7 +50,7 @@ import { buildIdNames } from './helpers/buildIdNames'
 import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
 import type { DepEntry } from './helpers/collectDeps'
-import { canonToType, canonKey } from './helpers/canonType'
+import { canonToType, canonToDtype, canonKey } from './helpers/canonType'
 import { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, deriveEntityNames, entityCollection } from './helpers/opShape'
 import { isReservedName, safeVarName, exampleVarName, isRbCoreConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
 import { serverVariables, hasServerVariables } from './helpers/serverVars'
@@ -456,10 +456,15 @@ export {
   isAuthActive,
   resolveAuthPrefix,
 
+  // Scaffold components need this to fail a generation with an actionable
+  // message rather than a bare Error (py-data guards on its sibling `py`).
+  SdkGenError,
+
   buildIdNames,
   getMatchEntries,
   collectDeps,
   canonToType,
+  canonToDtype,
   canonKey,
 
   OP_SUFFIX,

package/project/.sdk/tm/py/utility/register.py

@@ -1,68 +0,0 @@
-# ProjectName SDK utility registration
-
-from core.utility_type import ProjectNameUtility
-
-from utility.clean import clean_util
-from utility.done import done_util
-from utility.make_error import make_error_util
-from utility.feature_add import feature_add_util
-from utility.feature_hook import feature_hook_util
-from utility.feature_init import feature_init_util
-from utility.fetcher import fetcher_util
-from utility.make_fetch_def import make_fetch_def_util
-from utility.make_context import make_context_util
-from utility.make_options import make_options_util
-from utility.make_request import make_request_util
-from utility.make_response import make_response_util
-from utility.make_result import make_result_util
-from utility.make_point import make_point_util
-from utility.make_spec import make_spec_util
-from utility.make_url import make_url_util
-from utility.param import param_util
-from utility.prepare_auth import prepare_auth_util
-from utility.prepare_body import prepare_body_util
-from utility.prepare_headers import prepare_headers_util
-from utility.prepare_method import prepare_method_util
-from utility.prepare_params import prepare_params_util
-from utility.prepare_path import prepare_path_util
-from utility.prepare_query import prepare_query_util
-from utility.result_basic import result_basic_util
-from utility.result_body import result_body_util
-from utility.result_headers import result_headers_util
-from utility.transform_request import transform_request_util
-from utility.transform_response import transform_response_util
-
-
-def register_all(u):
-    u.clean = clean_util
-    u.done = done_util
-    u.make_error = make_error_util
-    u.feature_add = feature_add_util
-    u.feature_hook = feature_hook_util
-    u.feature_init = feature_init_util
-    u.fetcher = fetcher_util
-    u.make_fetch_def = make_fetch_def_util
-    u.make_context = make_context_util
-    u.make_options = make_options_util
-    u.make_request = make_request_util
-    u.make_response = make_response_util
-    u.make_result = make_result_util
-    u.make_point = make_point_util
-    u.make_spec = make_spec_util
-    u.make_url = make_url_util
-    u.param = param_util
-    u.prepare_auth = prepare_auth_util
-    u.prepare_body = prepare_body_util
-    u.prepare_headers = prepare_headers_util
-    u.prepare_method = prepare_method_util
-    u.prepare_params = prepare_params_util
-    u.prepare_path = prepare_path_util
-    u.prepare_query = prepare_query_util
-    u.result_basic = result_basic_util
-    u.result_body = result_body_util
-    u.result_headers = result_headers_util
-    u.transform_request = transform_request_util
-    u.transform_response = transform_response_util
-
-
-ProjectNameUtility._registrar = register_all