@voxgig/sdkgen-langpack 0.0.1

package/.sdk/tm/dart/lib/utility/GraphqlUtility.dart

@@ -0,0 +1,162 @@
+import 'voxgig_struct.dart' as vs;
+
+// 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 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`.
+String graphqlErrorCode(dynamic gqlerr) {
+  final ext = vs.getprop(gqlerr, 'extensions');
+
+  var raw = vs.getprop(ext, 'code');
+  if (null == raw || '' == raw) {
+    raw = vs.getprop(ext, 'type');
+  }
+  final code = (raw is String) ? raw.toUpperCase() : '';
+
+  if (code.contains('AUTH') ||
+      code.contains('FORBIDDEN') ||
+      code.contains('UNAUTHENTICATED')) {
+    return 'request_auth';
+  }
+  if (code.contains('RATELIMIT') ||
+      code.contains('RATE_LIMIT') ||
+      code.contains('TOO_MANY')) {
+    return 'request_ratelimit';
+  }
+  if (code.contains('BAD_USER_INPUT') ||
+      code.contains('VALIDATION') ||
+      code.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.
+dynamic graphqlBody(dynamic ctx) {
+  final gql = ctx.point?.graphql;
+
+  if (gql is! Map) {
+    return null;
+  }
+
+  // reqmatch/reqdata hold the caller's arguments for THIS call; data/match
+  // hold the entity's current state. Which pair depends on whether the op
+  // takes match or data input. A named variable falls back to the current
+  // state, so updating a loaded entity with just {title} still binds the
+  // stored id the mutation requires.
+  var reqsrc = ctx.reqmatch;
+  var datasrc = ctx.match;
+  if (null != ctx.op && 'data' == ctx.op.input) {
+    reqsrc = ctx.reqdata;
+    datasrc = ctx.data;
+  }
+  if (reqsrc is! Map) {
+    reqsrc = <String, dynamic>{};
+  }
+  if (datasrc is! Map) {
+    datasrc = <String, dynamic>{};
+  }
+
+  final variables = <String, dynamic>{};
+
+  final varlist = vs.getprop(gql, 'vars');
+  if (varlist is List) {
+    for (final spec in varlist) {
+      if (spec is! Map) {
+        continue;
+      }
+
+      final name = vs.getprop(spec, 'name');
+      final from = vs.getprop(spec, 'from');
+      if (null == name) {
+        continue;
+      }
+
+      if (null == from || '' == from) {
+        // The input object IS the request body. Strip the action selector,
+        // which is an SDK-side point discriminator, not an API field.
+        final body = <String, dynamic>{};
+        reqsrc.forEach((k, v) {
+          if ('\$action' != k) {
+            body[k.toString()] = v;
+          }
+        });
+        variables[name.toString()] = body;
+        continue;
+      }
+
+      // Only send variables the caller actually supplied: sending an
+      // explicit null would clear a field on many APIs.
+      final val = vs.getprop(reqsrc, from) ?? vs.getprop(datasrc, from);
+      if (null != val) {
+        variables[name.toString()] = val;
+      }
+    }
+  }
+
+  return {
+    '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.
+bool graphqlErrors(dynamic ctx) {
+  final result = ctx.result;
+
+  if (null == result || null == ctx.point) {
+    return false;
+  }
+
+  if ('graphql' != ctx.point.kind) {
+    return false;
+  }
+
+  final errors = vs.getprop(result.body, 'errors');
+  if (errors is! List || 0 == errors.length) {
+    return false;
+  }
+
+  final first = errors[0];
+  var msg = vs.getprop(first, 'message');
+  if (msg is! String || '' == msg) {
+    msg = 'graphql error';
+  }
+  if (1 < errors.length) {
+    msg = msg + ' (+' + (errors.length - 1).toString() + ' more)';
+  }
+
+  result.err = ctx.error(graphqlErrorCode(first), 'graphql: ' + msg);
+  result.ok = false;
+
+  return true;
+}

package/.sdk/tm/dart/lib/utility/MakeContextUtility.dart

@@ -0,0 +1,6 @@
+import '../Context.dart';
+
+dynamic makeContext(dynamic ctxmap, [dynamic basectx]) {
+  final ctx = Context(ctxmap, basectx);
+  return ctx;
+}

package/.sdk/tm/dart/lib/utility/MakeErrorUtility.dart

@@ -0,0 +1,71 @@
+import '../ProjectNameError.dart';
+import '../Result.dart';
+
+import 'CleanUtility.dart';
+import 'ErrUtility.dart';
+
+dynamic makeError(dynamic ctx, [dynamic err]) {
+  final op = ctx.op;
+  final opname =
+      (null == op || null == op.name) ? 'unknown operation' : op.name;
+
+  final result = ctx.result ?? Result({});
+  result.ok = false;
+
+  final reserr = result.err;
+
+  err ??= reserr;
+  err ??= ctx.error('unknown', 'unknown error');
+
+  // TODO: project name should come from config
+  // avoids spurious changes between template and generated utility
+  // applies for all utility files
+  final msg = 'ProjectNameSDK: ' + opname.toString() + ': ' + errmsg(err);
+
+  ProjectNameError sdkerr;
+  if (err is ProjectNameError) {
+    sdkerr = err;
+    sdkerr.message = clean(ctx, msg);
+  } else {
+    final code = errcode(err);
+    sdkerr = ProjectNameError('' == code ? 'unknown' : code, clean(ctx, msg), ctx);
+  }
+
+  if (null != result.err) {
+    result.err = null;
+  }
+
+  final spec = ctx.spec;
+
+  if (null != ctx.ctrl['explain']) {
+    ctx.ctrl['explain']['err'] = {
+      'code': sdkerr.code,
+      'message': sdkerr.message,
+    };
+  }
+
+  sdkerr.result = clean(ctx, result);
+  sdkerr.spec = clean(ctx, spec);
+
+  // Promote the HTTP status to the top level, so a consumer can branch on
+  // `err.status` / `err.notFound` instead of reaching into `err.result`.
+  sdkerr.status = null == result.status ? -1 : result.status;
+
+  ctx.ctrl['err'] = sdkerr;
+
+  // Fire PreUnexpected so observability features (metrics, telemetry, audit,
+  // debug) close/record error paths that never reach PreDone (e.g. a PrePoint
+  // rbac short-circuit). Fires after ctx.ctrl['err'] is set so hooks can read
+  // the error; features guard against double-recording when PreDone fired.
+  final utility = ctx.utility;
+  if (null != utility && null != utility.featureHook) {
+    utility.featureHook(ctx, 'PreUnexpected');
+  }
+
+  // TODO: model option to return instead
+  if (false == ctx.ctrl['throw']) {
+    return result.resdata;
+  } else {
+    throw sdkerr;
+  }
+}

package/.sdk/tm/dart/lib/utility/MakeFetchDefUtility.dart

@@ -0,0 +1,42 @@
+import '../Result.dart';
+
+import 'voxgig_struct.dart' as vs;
+
+import 'ErrUtility.dart';
+
+dynamic makeFetchDef(dynamic ctx) {
+  final spec = ctx.spec;
+  final utility = ctx.utility;
+  final makeUrl = utility.makeUrl;
+
+  if (null == spec) {
+    return ctx.error(
+        'fetchdef_no_spec', 'Expected context spec property to be defined.');
+  }
+
+  if (null == ctx.result) {
+    ctx.result = Result({});
+  }
+
+  spec.step = 'prepare';
+
+  final url = makeUrl(ctx);
+  if (iserr(url)) {
+    return url;
+  }
+
+  spec.url = url;
+
+  final fetchdef = <String, dynamic>{
+    'url': url,
+    'method': spec.method,
+    'headers': spec.headers,
+  };
+
+  if (null != spec.body) {
+    fetchdef['body'] =
+        vs.isnode(spec.body) ? vs.jsonify(spec.body) : spec.body;
+  }
+
+  return fetchdef;
+}

package/.sdk/tm/dart/lib/utility/MakeOptionsUtility.dart

@@ -0,0 +1,233 @@
+import '../ProjectNameError.dart';
+
+import 'voxgig_struct.dart' as vs;
+
+import 'FetcherUtility.dart';
+
+dynamic makeOptions(dynamic ctx) {
+  final utility = ctx.utility;
+  final options = ctx.options;
+
+  // Custom utility overrides.
+  final customUtils = vs.getprop(options, 'utility') ?? {};
+  for (final item in vs.items(customUtils)) {
+    utility.setUtility(item[0], item[1]);
+  }
+
+  final config = ctx.config ?? {};
+  final cfgopts = vs.getprop(config, 'options') ?? {};
+
+  // Standard SDK option values.
+  final optspec = {
+    'apikey': '',
+    'base': 'http://localhost:8000',
+    'secret': '',
+    'prefix': '',
+    'suffix': '',
+    // `basic` and `secret`: HTTP Basic Auth needs a second credential and a
+    // flag to say the pair is Basic rather than a single bearer token.
+    'auth': {
+      'prefix': '',
+      'basic': false,
+    },
+    'headers': {
+      '`\$CHILD`': '`\$STRING`',
+    },
+    'allow': {
+      'method': 'GET,PUT,POST,PATCH,DELETE,OPTIONS',
+      'op': 'create,update,load,list,remove,command,direct,graphql',
+    },
+    'entity': {
+      '`\$CHILD`': {
+        '`\$OPEN`': true,
+        'active': false,
+        'alias': {},
+      },
+    },
+    'feature': {
+      '`\$CHILD`': {
+        '`\$OPEN`': true,
+        'active': false,
+      },
+    },
+    'utility': {},
+    // Feature INSTANCES supplied at construction (the station adopt
+    // path): consumed by the constructor's featureAdd loop, so they are
+    // class instances, not data - `$ANY` accepts them verbatim. Without
+    // this entry the seam is dead: the constructor reads
+    // options.extend, but validate rejected the key.
+    'extend': '`\$ANY`',
+    'system': {},
+    'test': {
+      'active': false,
+      'entity': {
+        '`\$OPEN`': true,
+      },
+    },
+    'clean': {
+      'keys': 'key,token,id',
+    },
+    // Server-variable values for a templated base URL (OpenAPI server
+    // variables): {name} placeholders in "base" are substituted from this
+    // map at construction. Spec defaults arrive via the generated config;
+    // user values override them. Mirrors go's make_options optspec.
+    'server': {'`\$CHILD`': ''},
+  };
+
+  // Dart specific: preserve the (function-valued) system.fetch across
+  // merge/validate, defaulting to the dart:io transport.
+  final sysFetch = vs.getpath(options, 'system.fetch') ?? httpFetch;
+
+  // Feature add-order. `options.feature` may be given as an ordered List of
+  // { name, active, ...opts } entries (the List position IS the order in
+  // which features are added), or as a { name: {opts} } map. Normalize a
+  // List to a map (so merge/validate are unchanged) and remember the
+  // explicit order; a map defaults to test-first so the `test` mock
+  // transport is installed as the base of the transport wrapper chain.
+  final featureorder = <String>[];
+  dynamic mergeOptions = options ?? {};
+  final rawFeature = vs.getprop(options, 'feature');
+  if (rawFeature is List) {
+    final fmap = <String, dynamic>{};
+    for (final entry in rawFeature) {
+      if (entry is Map && null != vs.getprop(entry, 'name')) {
+        final fname = vs.getprop(entry, 'name').toString();
+        final fopts = <String, dynamic>{};
+        entry.forEach((k, v) {
+          if ('name' != k) {
+            fopts[k.toString()] = v;
+          }
+        });
+        fmap[fname] = fopts;
+        featureorder.add(fname);
+      }
+    }
+    mergeOptions = vs.clone(options);
+    mergeOptions['feature'] = fmap;
+  }
+
+  // `auth: null` is the documented way to disable auth outright, and
+  // prepareAuth honours it before it ever reads the apikey. It cannot survive
+  // validate: depending on the struct port a stored null is either REPLACED
+  // by the optspec default — transmitting the credential the caller withheld
+  // — or REJECTED outright. Withhold the key for validate, then put the null
+  // back. Same fix as ts/js/go makeOptions.
+  //
+  // Suppliedness cannot be recovered after validate, hence here, and it must
+  // tell an ABSENT auth from a present null: containsKey rather than a null
+  // check on the value, which cannot distinguish them.
+  final authSuppressed =
+      options is Map && options.containsKey('auth') && null == options['auth'];
+
+  // User option maps are cloned first — their (possibly narrow) literal
+  // types must not constrain the merged structures.
+  dynamic opts = vs.merge([{}, cfgopts, vs.clone(mergeOptions)]);
+
+  if (authSuppressed && opts is Map) {
+    opts.remove('auth');
+  }
+
+  opts = vs.validate(opts, optspec);
+
+  // Restore the suppression the optspec default would otherwise erase.
+  if (authSuppressed && opts is Map) {
+    opts['auth'] = null;
+  }
+
+  // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
+  // Every placeholder must resolve to a non-empty value: from options.server
+  // (user), else the Config default. A placeholder that resolves to '' is a
+  // construction ERROR in live mode — the URL cannot work — but in test mode
+  // substitutes the deterministic value `test-<name>` so offline tests need no
+  // configuration. The SDK constructor has no error return, so a missing
+  // required variable THROWS: construction-time misconfiguration.
+  final baseVal = vs.getprop(opts, 'base');
+  if (baseVal is String && baseVal.contains('{')) {
+    final testmode = true == vs.getpath(opts, 'test.active') ||
+        true == vs.getpath(opts, 'feature.test.active');
+    final server = vs.getprop(opts, 'server') ?? {};
+    final sdkname = (vs.getpath(config, 'main.name') ?? 'SDK').toString();
+
+    opts['base'] = baseVal.replaceAllMapped(
+      RegExp(r'\{([A-Za-z0-9_]+)\}'),
+      (m) {
+        final name = m.group(1) as String;
+        final raw = vs.getprop(server, name);
+        final val = raw is String ? raw : '';
+        if ('' == val) {
+          if (testmode) {
+            return 'test-' + name;
+          }
+          throw ProjectNameError(
+            'server_var_required',
+            "$sdkname: the server variable '$name' is required: the API base "
+            "URL is '$baseVal' — pass { 'server': { '$name': '...' } } in the "
+            'SDK options',
+          );
+        }
+        return val;
+      },
+    );
+  }
+
+  final sys = vs.getprop(opts, 'system');
+  if (sys is Map) {
+    sys['fetch'] = sysFetch;
+  } else {
+    opts['system'] = {'fetch': sysFetch};
+  }
+
+  final cleanKeys =
+      (vs.getpath(opts, 'clean.keys') ?? 'key,token,id').toString();
+
+  final parts = <String>[];
+  for (final part in cleanKeys.split(',')) {
+    final trimmed = part.trim();
+    if ('' != trimmed) {
+      parts.add(vs.escre(trimmed));
+    }
+  }
+  final keyre = parts.join('|');
+
+  // Resolve the feature add-order: an explicit List order (above) wins;
+  // otherwise order the map test-first, then the remaining names sorted, so
+  // the outcome is deterministic and `test` is always the base transport.
+  if (0 == featureorder.length) {
+    final featureMap = vs.getprop(opts, 'feature') ?? {};
+    final names = <String>[];
+    for (final it in vs.items(featureMap)) {
+      names.add(it[0].toString());
+    }
+    names.sort();
+    if (names.contains('test')) {
+      featureorder.add('test');
+      for (final n in names) {
+        if ('test' != n) {
+          featureorder.add(n);
+        }
+      }
+    } else {
+      featureorder.addAll(names);
+    }
+    // Station special case, mirroring test's: its transport wrap must
+    // sit immediately outside the base transport (inside retry/cache/
+    // netsim), so map-form activation hoists it to just after test -
+    // or first, when no test entry exists. Without this the sorted
+    // default would init station last and wrap OUTSIDE the recording
+    // features, turning its wire-truth events into fiction.
+    if (featureorder.contains('station')) {
+      featureorder.remove('station');
+      final ti = featureorder.indexOf('test');
+      featureorder.insert(-1 == ti ? 0 : ti + 1, 'station');
+    }
+  }
+
+  opts['__derived__'] = {
+    'clean': {
+      'keyre': '' == keyre ? null : keyre,
+    },
+    'featureorder': featureorder,
+  };
+
+  return opts;
+}

package/.sdk/tm/dart/lib/utility/MakePointUtility.dart

@@ -0,0 +1,130 @@
+import 'voxgig_struct.dart' as vs;
+
+dynamic makePoint(dynamic ctx) {
+  if (null != ctx.out['point']) {
+    return ctx.point = ctx.out['point'];
+  }
+
+  final op = ctx.op;
+  final options = ctx.options;
+
+  final allowop = (vs.getpath(options, 'allow.op') ?? '').toString();
+  if (!allowop.contains(op.name.toString())) {
+    return ctx.error(
+        'point_op_allow',
+        'Operation "' +
+            op.name.toString() +
+            '" not allowed by SDK option allow.op value: "' +
+            allowop +
+            '"');
+  }
+
+  if (0 == op.points.length) {
+    return ctx.error(
+        'point_no_points',
+        'Operation "' + op.name.toString() + '" has no endpoint definitions.');
+  }
+
+  // Choose the appropriate point based on the match or data.
+  if (1 == op.points.length) {
+    ctx.point = op.points[0];
+  } else {
+    // Operation argument has priority, but also look in current data or match.
+    final reqselector = 'data' == op.input ? ctx.reqdata : ctx.reqmatch;
+    final selector = 'data' == op.input ? ctx.data : ctx.match;
+
+    dynamic point;
+    var matched = false;
+    for (var i = 0; i < op.points.length; i++) {
+      final cand = op.points[i];
+      final select = cand.select;
+      var found = true;
+
+      final exist = vs.getprop(select, 'exist');
+      if (null != selector && exist is List) {
+        for (var j = 0; j < exist.length; j++) {
+          final existkey = exist[j];
+
+          if (null == vs.getprop(reqselector, existkey) &&
+              null == vs.getprop(selector, existkey)) {
+            found = false;
+            break;
+          }
+        }
+      }
+
+      // Action is only in operation argument.
+      if (found &&
+          vs.getprop(reqselector, r'$action') !=
+              vs.getprop(select, r'$action')) {
+        found = false;
+      }
+
+      if (found) {
+        point = cand;
+        matched = true;
+        break;
+      }
+    }
+
+    // select.exist can list more than the params needed to pick a point, so
+    // nothing matches — fall back to the entity's own route rather than
+    // whichever point came last.
+    if (!matched) {
+      // A request naming an action reaches here only because that action's
+      // own point failed its exist test, so it is unbuildable whatever we
+      // pick. Refuse it BEFORE choosing a fallback: the guard below compares
+      // the chosen point's $action and would wave the request through
+      // whenever the fallback lands on the action point itself.
+      if (null != vs.getprop(reqselector, r'$action')) {
+        return ctx.error(
+            'point_action_invalid',
+            'Operation "' +
+                op.name.toString() +
+                '" action "' +
+                vs.getprop(reqselector, r'$action').toString() +
+                '" is not valid.');
+      }
+
+      // A terminal parameter marks a record route (/boards/{id}); a
+      // cross-reference ends in the relationship's name
+      // (/posts/{id}/author). Failing that, the shallower path wins.
+      bool terminalParam(dynamic p) {
+        final parts = p.parts;
+        if (parts.isEmpty) {
+          return false;
+        }
+        final last = parts[parts.length - 1];
+        return last is String && last.startsWith('{');
+      }
+
+      point = op.points[0];
+      for (final cand in op.points) {
+        if (terminalParam(cand) != terminalParam(point)) {
+          if (terminalParam(cand)) {
+            point = cand;
+          }
+        } else if (cand.parts.length < point.parts.length) {
+          point = cand;
+        }
+      }
+    }
+
+    if (null != vs.getprop(reqselector, r'$action') &&
+        null != point &&
+        vs.getprop(reqselector, r'$action') !=
+            vs.getprop(point.select, r'$action')) {
+      return ctx.error(
+          'point_action_invalid',
+          'Operation "' +
+              op.name.toString() +
+              '" action "' +
+              vs.getprop(reqselector, r'$action').toString() +
+              '" is not valid.');
+    }
+
+    ctx.point = point;
+  }
+
+  return ctx.point;
+}