@voxgig/sdkgen-langpack 0.0.1

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

@@ -0,0 +1,66 @@
+import 'dart:async';
+
+import '../Response.dart';
+import '../Result.dart';
+
+import 'ErrUtility.dart';
+
+Future<dynamic> makeRequest(dynamic ctx) async {
+  // PreRequest feature hook has already provided a result.
+  if (null != ctx.out['request']) {
+    return ctx.out['request'];
+  }
+
+  final spec = ctx.spec;
+  final utility = ctx.utility;
+  final fetcher = utility.fetcher;
+  final makeFetchDef = utility.makeFetchDef;
+
+  var response = Response({});
+
+  final result = Result({});
+
+  ctx.result = result;
+
+  if (null == spec) {
+    return ctx.error(
+        'request_no_spec', 'Expected context spec property to be defined.');
+  }
+
+  try {
+    final fetchdef = makeFetchDef(ctx);
+    if (iserr(fetchdef)) {
+      throw fetchdef;
+    }
+
+    if (null != ctx.ctrl['explain']) {
+      ctx.ctrl['explain']['fetchdef'] = fetchdef;
+    }
+
+    spec.step = 'prerequest';
+
+    // `dynamic` (not the inferred non-nullable type): the fetcher is injected
+    // and may return null at runtime, so the null guard below is real — an
+    // inferred non-null type would make it an `unnecessary_null_comparison`.
+    final dynamic fetched =
+        await Future.value(fetcher(ctx, fetchdef['url'], fetchdef));
+
+    if (null == fetched) {
+      response = Response({
+        'err': ctx.error('request_no_response', 'response: undefined')
+      });
+    } else if (iserr(fetched)) {
+      response = Response({'err': fetched});
+    } else {
+      response = Response(fetched);
+    }
+  } catch (err) {
+    response.err = err;
+  }
+
+  spec.step = 'postrequest';
+
+  ctx.response = response;
+
+  return response;
+}

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

@@ -0,0 +1,59 @@
+import 'dart:async';
+
+Future<dynamic> makeResponse(dynamic ctx) async {
+  // PreResponse feature hook has already provided a result.
+  if (null != ctx.out['response']) {
+    return ctx.out['response'];
+  }
+
+  final utility = ctx.utility;
+  final resultBasic = utility.resultBasic;
+  final resultHeaders = utility.resultHeaders;
+  final resultBody = utility.resultBody;
+  final transformResponse = utility.transformResponse;
+
+  final spec = ctx.spec;
+  final result = ctx.result;
+  final response = ctx.response;
+
+  if (null == spec) {
+    return ctx.error(
+        'response_no_spec', 'Expected context spec property to be defined.');
+  }
+
+  if (null == response) {
+    return ctx.error('response_no_response',
+        'Expected context response property to be defined.');
+  }
+
+  if (null == result) {
+    return ctx.error('response_no_result',
+        'Expected context result property to be defined.');
+  }
+
+  spec.step = 'response';
+
+  try {
+    resultBasic(ctx);
+    resultHeaders(ctx);
+    await Future.value(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);
+    transformResponse(ctx);
+
+    if (null == result.err) {
+      result.ok = true;
+    }
+  } catch (err) {
+    result.err = err;
+  }
+
+  if (null != ctx.ctrl['explain']) {
+    ctx.ctrl['explain']['result'] = result;
+  }
+
+  return response;
+}

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

@@ -0,0 +1,49 @@
+dynamic makeResult(dynamic ctx) {
+  // PreResult feature hook has already provided a result.
+  if (null != ctx.out['result']) {
+    return ctx.out['result'];
+  }
+
+  final utility = ctx.utility;
+  final transformResponse = utility.transformResponse;
+
+  final op = ctx.op;
+  final entity = ctx.entity;
+
+  final spec = ctx.spec;
+  final result = ctx.result;
+
+  if (null == spec) {
+    return ctx.error(
+        'result_no_spec', 'Expected context spec property to be defined.');
+  }
+
+  if (null == result) {
+    return ctx.error(
+        'result_no_result', 'Expected context result property to be defined.');
+  }
+
+  spec.step = 'result';
+
+  transformResponse(ctx);
+
+  if ('list' == op.name) {
+    final resdata = result.resdata;
+    result.resdata = [];
+
+    if (resdata is List && 0 < resdata.length) {
+      for (final entry in resdata) {
+        final ent = entity.make();
+        ent.data(entry);
+        result.resdata.add(ent);
+      }
+    }
+  }
+
+  if (null != ctx.ctrl['explain']) {
+    ctx.ctrl['explain']['result'] = result;
+  }
+
+  // NOTE: returns processed result.
+  return result;
+}

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

@@ -0,0 +1,77 @@
+import 'GraphqlUtility.dart';
+import '../Spec.dart';
+
+import 'ErrUtility.dart';
+
+// Create request specification.
+dynamic makeSpec(dynamic ctx) {
+  if (null != ctx.out['spec']) {
+    return ctx.spec = ctx.out['spec'];
+  }
+
+  final point = ctx.point;
+  final options = ctx.options;
+  final utility = ctx.utility;
+
+  final prepareMethod = utility.prepareMethod;
+  final prepareParams = utility.prepareParams;
+  final prepareQuery = utility.prepareQuery;
+  final prepareHeaders = utility.prepareHeaders;
+  final prepareBody = utility.prepareBody;
+  final preparePath = utility.preparePath;
+  final prepareAuth = utility.prepareAuth;
+
+  ctx.spec = Spec({
+    'base': options['base'], // string, URL endpoint base prefix,
+    'prefix': options['prefix'],
+    'parts': point.parts,
+    'suffix': options['suffix'],
+    'step': 'start',
+  });
+
+  ctx.spec.method = prepareMethod(ctx);
+
+  final allowmethod = (options['allow']?['method'] ?? '').toString();
+  if (!allowmethod.contains(ctx.spec.method.toString())) {
+    return ctx.error(
+        'spec_method_allow',
+        'Method "' +
+            ctx.spec.method.toString() +
+            '" not allowed by SDK option allow.method value: "' +
+            allowmethod +
+            '"');
+  }
+
+  ctx.spec.params = prepareParams(ctx);
+  ctx.spec.query = prepareQuery(ctx);
+  ctx.spec.headers = prepareHeaders(ctx);
+
+  if ('graphql' == point.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, 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 = <String, dynamic>{};
+    ctx.spec.headers['content-type'] = graphqlContentType;
+  } else {
+    ctx.spec.body = prepareBody(ctx);
+    ctx.spec.path = preparePath(ctx);
+  }
+
+  if (null != ctx.ctrl['explain']) {
+    ctx.ctrl['explain']['spec'] = ctx.spec;
+  }
+
+  final spec = prepareAuth(ctx);
+
+  if (!iserr(spec)) {
+    ctx.spec = spec;
+  }
+
+  return spec;
+}

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

@@ -0,0 +1,51 @@
+import 'voxgig_struct.dart' as vs;
+
+dynamic makeUrl(dynamic ctx) {
+  final spec = ctx.spec;
+  final result = ctx.result;
+
+  if (null == spec) {
+    return ctx.error(
+        'url_no_spec', 'Expected context spec property to be defined.');
+  }
+
+  if (null == result) {
+    return ctx.error(
+        'url_no_result', 'Expected context result property to be defined.');
+  }
+
+  // TODO: use parts to avoid regexp?
+  var url =
+      vs.join([spec.base, spec.prefix, spec.path, spec.suffix], '/', true);
+  final resmatch = <String, dynamic>{};
+
+  final params = spec.params;
+
+  for (final item in vs.items(params)) {
+    final key = item[0];
+    final val = item[1];
+    if (null != val) {
+      url = url.replaceFirst(
+          RegExp('\\{' + vs.escre(key) + '\\}'), vs.escurl(val.toString()));
+      resmatch[key] = val;
+    }
+  }
+
+  // Append query string from spec.query. Entity ops populate this via
+  // PrepareQueryUtility from the operation's reqmatch; direct() callers
+  // pass it as fetchargs.query.
+  var qsep = '?';
+  for (final item in vs.items(spec.query)) {
+    final key = item[0];
+    final val = item[1];
+    if (null != val) {
+      url = url + qsep + vs.escurl(key) + '=' + vs.escurl(val.toString());
+      qsep = '&';
+      resmatch[key] = val;
+    }
+  }
+
+  result.resmatch = resmatch;
+
+  return url;
+}

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

@@ -0,0 +1,56 @@
+import 'voxgig_struct.dart' as vs;
+
+/* Find value of a match parameter, possibly using an alias.
+ *
+ * The match parameter may have an alias key. For example, the parameter
+ * `foo_id` may be aliased to `id` in the entity data.
+ *
+ * This function returns null rather than failing.
+ */
+dynamic param(dynamic ctx, dynamic paramdef) {
+  final point = ctx.point;
+  final spec = ctx.spec;
+  final match = ctx.match;
+  final reqmatch = ctx.reqmatch;
+  final data = ctx.data;
+  final reqdata = ctx.reqdata;
+
+  // TODO: review this search algorithm
+
+  final key =
+      paramdef is String ? paramdef : vs.getprop(paramdef, 'name');
+
+  final akey = null == point ? null : vs.getprop(point.alias, key);
+
+  dynamic val = vs.getprop(reqmatch, key);
+
+  if (null == val) {
+    val = vs.getprop(match, key);
+  }
+
+  if (null == val && null != akey) {
+    if (null != spec) {
+      vs.setprop(spec.alias, akey, key);
+    }
+
+    val = vs.getprop(reqmatch, akey);
+  }
+
+  if (null == val) {
+    val = vs.getprop(reqdata, key);
+  }
+
+  if (null == val) {
+    val = vs.getprop(data, key);
+  }
+
+  if (null == val && null != akey) {
+    val = vs.getprop(reqdata, akey);
+
+    if (null == val) {
+      val = vs.getprop(data, akey);
+    }
+  }
+
+  return val;
+}

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

@@ -0,0 +1,46 @@
+import 'voxgig_struct.dart' as vs;
+
+const HEADER_auth = 'authorization';
+
+const OPTION_apikey = 'apikey';
+
+const NOTFOUND = '__NOTFOUND__';
+
+dynamic prepareAuth(dynamic ctx) {
+  final client = ctx.client;
+  final spec = ctx.spec;
+
+  if (null == spec) {
+    return ctx.error(
+        'auth_no_spec', 'Expected context spec property to be defined.');
+  }
+
+  final headers = spec.headers;
+
+  final options = client.options();
+
+  // Public APIs that need no auth omit the options.auth block entirely.
+  if (null == vs.getprop(options, 'auth')) {
+    vs.delprop(headers, HEADER_auth);
+    return spec;
+  }
+
+  final prefix = vs.getpath(options, 'auth.prefix');
+
+  final apikey = vs.getprop(options, OPTION_apikey, NOTFOUND);
+
+  if (NOTFOUND == apikey || null == apikey || '' == apikey) {
+    vs.delprop(headers, HEADER_auth);
+  } else {
+    // A raw credential (empty prefix, e.g. an apiKey scheme) must go in
+    // as-is; only a non-empty prefix (Bearer/Basic/OAuth) is space-joined.
+    vs.setprop(
+        headers,
+        HEADER_auth,
+        (null != prefix && '' != prefix)
+            ? prefix.toString() + ' ' + apikey.toString()
+            : apikey);
+  }
+
+  return spec;
+}

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

@@ -0,0 +1,19 @@
+dynamic prepareBody(dynamic ctx) {
+  final op = ctx.op;
+
+  final utility = ctx.utility;
+  final error = utility.makeError;
+  final transformRequest = utility.transformRequest;
+
+  dynamic body;
+
+  if ('data' == op.input) {
+    try {
+      body = transformRequest(ctx);
+    } catch (err) {
+      return error(ctx, err);
+    }
+  }
+
+  return body;
+}

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

@@ -0,0 +1,11 @@
+import 'voxgig_struct.dart' as vs;
+
+dynamic prepareHeaders(dynamic ctx) {
+  final client = ctx.client;
+
+  final options = client.options();
+
+  final out = vs.clone(vs.getprop(options, 'headers', {}));
+
+  return out;
+}

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

@@ -0,0 +1,30 @@
+import 'voxgig_struct.dart' as vs;
+
+dynamic prepareMethod(dynamic ctx) {
+  final op = ctx.op;
+  final opname = op.name;
+
+  final methodMap = {
+    'create': 'POST',
+    'update': 'PUT',
+    'load': 'GET',
+    'list': 'GET',
+    'remove': 'DELETE',
+    'patch': 'PATCH',
+  };
+
+  // The API definition is authoritative: a POST-only or PATCH-based API
+  // exposes `update` as POST or PATCH, not the PUT the op name implies.
+  // Only fall back to the op-name convention when the point has no method.
+  // Read the field off the Point object directly: vs.getprop only handles
+  // maps and lists, so going through it always missed the point's method and
+  // fell back to the op-name convention below. A GraphQL point synthesizes
+  // POST for every op, and a POST-only or PATCH-based REST API states its own
+  // method too — both were being overridden.
+  final method = ctx.point?.method;
+  if (method is String && '' != method) {
+    return method.toUpperCase();
+  }
+
+  return methodMap[opname];
+}

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

@@ -0,0 +1,23 @@
+import 'voxgig_struct.dart' as vs;
+
+dynamic prepareParams(dynamic ctx) {
+  final utility = ctx.utility;
+  final findparam = utility.param;
+
+  final point = ctx.point;
+
+  final params = vs.getprop(point.args, 'params') ?? [];
+
+  final out = <String, dynamic>{};
+  for (final pd in params) {
+    final val = findparam(ctx, pd);
+    if (null != val) {
+      out[vs.getprop(pd, 'name').toString()] = val;
+    }
+  }
+
+  // TODO: review
+  // out = validate(out, point.validate.params)
+
+  return out;
+}

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

@@ -0,0 +1,9 @@
+import 'voxgig_struct.dart' as vs;
+
+dynamic preparePath(dynamic ctx) {
+  final point = ctx.point;
+
+  final path = vs.join(point.parts, '/', true);
+
+  return path;
+}

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

@@ -0,0 +1,18 @@
+import 'voxgig_struct.dart' as vs;
+
+dynamic prepareQuery(dynamic ctx) {
+  final point = ctx.point;
+  final params = point.params ?? [];
+  final reqmatch = ctx.reqmatch ?? {};
+
+  final out = <String, dynamic>{};
+  for (final item in vs.items(reqmatch)) {
+    final key = item[0];
+    final val = item[1];
+    if (null != val && !(params as List).contains(key)) {
+      out[key] = val;
+    }
+  }
+
+  return out;
+}

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

@@ -0,0 +1,29 @@
+import 'ErrUtility.dart';
+
+dynamic resultBasic(dynamic ctx) {
+  final response = ctx.response;
+  final result = ctx.result;
+
+  if (null != result && null != response) {
+    result.status = response.status ?? -1;
+    result.statusText = response.statusText ?? 'no-status';
+
+    // TODO: use spec!
+    if (result.status is num && 400 <= result.status) {
+      final msg = 'request: ' +
+          result.status.toString() +
+          ': ' +
+          result.statusText.toString();
+      if (null != result.err) {
+        final prevmsg = errmsg(result.err);
+        result.err = ctx.error('request_status', prevmsg + ': ' + msg);
+      } else {
+        result.err = ctx.error('request_status', msg);
+      }
+    } else if (null != response.err) {
+      result.err = response.err;
+    }
+  }
+
+  return result;
+}

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

@@ -0,0 +1,15 @@
+import 'dart:async';
+
+Future<dynamic> resultBody(dynamic ctx) async {
+  final response = ctx.response;
+  final result = ctx.result;
+
+  if (null != result) {
+    if (null != response && null != response.jsonFn && null != response.body) {
+      final json = await response.json();
+      result.body = json;
+    }
+  }
+
+  return result;
+}

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

@@ -0,0 +1,18 @@
+dynamic resultHeaders(dynamic ctx) {
+  final response = ctx.response;
+  final result = ctx.result;
+
+  if (null != result) {
+    if (null != response && response.headers is Map) {
+      final headers = <String, dynamic>{};
+      (response.headers as Map).forEach((k, v) {
+        headers[k.toString()] = v;
+      });
+      result.headers = headers;
+    } else {
+      result.headers = <String, dynamic>{};
+    }
+  }
+
+  return result;
+}