@voxgig/sdkgen 4.9.0 → 4.10.0

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

@@ -1,162 +0,0 @@
-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/project/.sdk/tm/dart/lib/utility/MakeContextUtility.dart

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

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

@@ -1,71 +0,0 @@
-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/project/.sdk/tm/dart/lib/utility/MakeFetchDefUtility.dart

@@ -1,42 +0,0 @@
-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/project/.sdk/tm/dart/lib/utility/MakeOptionsUtility.dart

@@ -1,233 +0,0 @@
-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/project/.sdk/tm/dart/lib/utility/MakePointUtility.dart

@@ -1,130 +0,0 @@
-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;
-}