@compassdigital/sdk.typescript 3.0.0-beta.8 → 3.0.0-rc.1

package/README.md

@@ -8,33 +8,146 @@ Compass Digital Labs TypeScript SDK
 $ npm install --save @compassdigital/sdk.typescript@latest
 ```
 
+## Example Server Usage
+
+``` typescript
+import Provider from "@compassdigital/provider";
+import { GetTaskRequest, GetTaskResponse } from "@compassdigital/sdk.typescript/interface/task";
+
+const provider = new Provider({ type: "payment" });
+
+provider.on<GetTaskRequest, GetTaskResponse>("get_task", function (req, next): void {
+    // ...
+})
+```
+
 ## Example Client Usage
 
+**Instanciate Client:**
+
 ``` typescript
 import { ServiceClient } from "@compassdigital/sdk.typescript";
 
 const api = new ServiceClient({ stage: "dev" });
+```
 
-async function main() {
-    const task = await api.get_task(task_id);
+**Basic Request:**
+
+``` typescript
+const task = await api.get_task(id);
+```
+
+**Request Options:**
+
+* These options may be passed to any request.
+
+``` typescript
+interface RequestOptions {
+  // environment to make requests to
+  stage?: string;
+  // authentication token
+  token?: string;
+  // additional headers
+  headers?: Record<string, string>;
+  // log all requests and responses
+  debug?: boolean;
+  // the number of times to retry a request
+  retry?: number;
+  // make requests against this base url
+  // note: the stage property is ignored if base_url is set
+  base_url?: string;
+  // intercept outgoing http requests
+  intercept?: InterceptFn;
 }
 ```
 
-## Example Server Usage
+* The `RequestOptions` can be provided to the `ServiceClient` constructor or at the request call site.
+* The options provided at the call site will overide options passed to the constructor.
 
 ``` typescript
-import Provider from "@compassdigital/provider";
-import { GetTaskRequest, GetTaskResponse } from "@compassdigital/sdk.typescript/task";
 
-const provider = new Provider({ type: "payment" });
+const api = new ServiceClient({
+    token: "<token>",
+    retry: 2,
+})
 
-provider.on<GetTaskRequest, GetTaskResponse>("get_task", function (req, next): void {
-    // ...
+const location = await api.get_location(id, {
+    token: "<token>",
+    retry: 2,
 })
 ```
 
+**Error Handling:**
+
+* non-200 responses are rejected with a `ServiceError`.
+
+``` typescript
+try {
+    const shoppingcart = await api.get_shoppingcart(id);
+} catch (err) {
+    // Since the error type is `unknown` we must type assert before
+    // accessing the properties.
+    if (err instanceof ServiceError) {
+        console.log(err.status, err.code, err.message);
+    }
+
+    // There are helpers for accessing the status and code
+    if (ServiceError.code(err) === 400.31) {
+        console.log("Failed to get menu");
+    }
+}
+```
+
+* There is a `ignore` convenience method for ignoring specific status & error codes.
+
+``` typescript
+const issue: OrderIssue = { items: [] };
+await api.post_order_issue(id, issue).ignore(400.18, 400.21);
+```
+
+* There is a `combine` convenience method for returning an object which contains the response or error.
+
+``` typescript
+const res = await api.get_task(id).combine();
+
+if (res.ok) {
+  console.log("task", res.data);
+} else {
+  console.log("error", res.err);
+}
+```
+
+**Testing:**
+
+* You can register an `intercept` function which will recieve all request.
+
+``` typescript
+
+import {
+  ServiceClient,
+  RequestData,
+  ResponseData,
+  FetchFn,
+} from "@compassdigital/sdk.typescript";
+
+async function intercept(req: RequestData, fetch: FetchFn): Promise<ResponseData> {
+    expect(req.name).toBe("get_shoppingcart");
+    return { ok: true, status: 200, body: JSON.stringify({}) }
+}
+
+const api = new ServiceClient({ intercept });
+```
+
 ## Code Gen
 
 1. Add new services to `manifest.json`.
 2. Run `npm run gen`.
 
+## Ad-Hoc Code Gen
+
+If you need types for a service you're working on and the sdk hasn't been updated yet, then
+you can generate local types from your swagger.
+
+```
+$ sdk.typescript --swagger ./swagger.json --service my_service > types/my_service.d.ts
+```

package/bin/gen.js

@@ -0,0 +1,484 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+exports.__esModule = true;
+exports.CodeGenerator = void 0;
+var fs_1 = __importDefault(require("fs"));
+var openapi_ts_1 = require("@icholy/openapi-ts");
+var prettier_1 = __importDefault(require("prettier"));
+var path_1 = __importDefault(require("path"));
+var ejs_1 = __importDefault(require("ejs"));
+var yargs_1 = __importDefault(require("yargs/yargs"));
+var helpers_1 = require("yargs/helpers");
+/**
+ * This is a mapping between "${method} ${path}" and the default
+ * operationId.
+ */
+var operationIDs = {
+    "get /location/group/{id}/deliverydestination": "get_location_group_deliverydestinations",
+    "get /location/search": "get_location_search",
+    "get /promo": "get_promos",
+    "get /schedule": "get_schedules",
+    "get /brand": "get_brands",
+    "get /announcement/resource": "get_resources",
+    "get /order/location/brand/{id}": "get_order_location_brand"
+};
+var CodeGenerator = /** @class */ (function () {
+    function CodeGenerator() {
+        this.imports = [];
+        this.methods = [];
+    }
+    CodeGenerator.prototype.manifest = function (manifest) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _i, _a, service, code_1, filename_1, code, filename;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0: 
+                    // generate service types
+                    return [4 /*yield*/, fs_1["default"].promises.mkdir(path_1["default"].join("src", "interface"), { recursive: true })];
+                    case 1:
+                        // generate service types
+                        _b.sent();
+                        _i = 0, _a = manifest.services;
+                        _b.label = 2;
+                    case 2:
+                        if (!(_i < _a.length)) return [3 /*break*/, 6];
+                        service = _a[_i];
+                        console.log("reading: " + service.swagger);
+                        return [4 /*yield*/, this.service(service, false)];
+                    case 3:
+                        code_1 = _b.sent();
+                        filename_1 = path_1["default"].join("src", "interface", service.name + ".ts");
+                        return [4 /*yield*/, fs_1["default"].promises.writeFile(filename_1, code_1)];
+                    case 4:
+                        _b.sent();
+                        _b.label = 5;
+                    case 5:
+                        _i++;
+                        return [3 /*break*/, 2];
+                    case 6: return [4 /*yield*/, this.client()];
+                    case 7:
+                        code = _b.sent();
+                        filename = path_1["default"].join("src", "index.ts");
+                        return [4 /*yield*/, fs_1["default"].promises.writeFile(filename, code)];
+                    case 8:
+                        _b.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    CodeGenerator.prototype.client = function () {
+        var _a;
+        var _b;
+        return __awaiter(this, void 0, void 0, function () {
+            var print, imports, _i, _c, _import, _d, _e, _f, path_2, names, template;
+            return __generator(this, function (_g) {
+                print = new openapi_ts_1.Printer();
+                // "do not modify" warning
+                print.comment("THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY");
+                print.blank();
+                imports = {};
+                for (_i = 0, _c = this.imports; _i < _c.length; _i++) {
+                    _import = _c[_i];
+                    (_a = imports[_b = _import.path]) !== null && _a !== void 0 ? _a : (imports[_b] = []);
+                    imports[_import.path].push(_import.name);
+                }
+                for (_d = 0, _e = Object.entries(imports); _d < _e.length; _d++) {
+                    _f = _e[_d], path_2 = _f[0], names = _f[1];
+                    print["import"](path_2, names);
+                    print.blank();
+                }
+                template = fs_1["default"].readFileSync("template.ejs", "utf-8");
+                print.raw(ejs_1["default"].render(template, { methods: this.methods }));
+                return [2 /*return*/, prettier_1["default"].format(print.code(), { parser: "typescript", printWidth: 100 })];
+            });
+        });
+    };
+    CodeGenerator.prototype.service = function (service, ambient) {
+        return __awaiter(this, void 0, void 0, function () {
+            var print, doc, details;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        print = new openapi_ts_1.Printer();
+                        return [4 /*yield*/, (0, openapi_ts_1.load)(service.swagger)];
+                    case 1:
+                        doc = _a.sent();
+                        details = (0, openapi_ts_1.analyse)(doc);
+                        this.transform(details, print, service, ambient);
+                        return [2 /*return*/, prettier_1["default"].format(print.code(), { parser: "typescript", printWidth: 100 })];
+                }
+            });
+        });
+    };
+    /**
+     * Add an import that the client will need.
+     */
+    CodeGenerator.prototype.addImport = function (service, name) {
+        this.imports.push({
+            name: name,
+            path: "./interface/" + service.name
+        });
+    };
+    /**
+     * Generate typescript code from the document details.
+     */
+    CodeGenerator.prototype.transform = function (doc, print, service, ambient) {
+        // "do not modify" warning
+        print.comment("THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY");
+        print.blank();
+        // declaration if it's ambient
+        if (ambient) {
+            print.raw("declare module \"@compassdigital/sdk.typescript/interface/" + service.name + "\" {");
+        }
+        // definitions
+        for (var _i = 0, _a = Object.entries(doc.definitions); _i < _a.length; _i++) {
+            var _b = _a[_i], name_1 = _b[0], schema = _b[1];
+            print.schema(schema, name_1);
+            print.blank();
+        }
+        // routes
+        for (var _c = 0, _d = doc.operations; _c < _d.length; _c++) {
+            var op = _d[_c];
+            var params = op.params, path_3 = op.path;
+            for (var _e = 0, _f = params.skipped; _e < _f.length; _e++) {
+                var skipped = _f[_e];
+                console.warn("SKIPPED", skipped);
+            }
+            // add missing path parameters
+            for (var _g = 0, _h = this.findPathParams(path_3); _g < _h.length; _g++) {
+                var name_2 = _h[_g];
+                if (!params.path.properties[name_2]) {
+                    params.path.setProperty(name_2, new openapi_ts_1.Schema("string", {
+                        required: true,
+                        description: "TODO: add parameter to swagger.json"
+                    }));
+                }
+            }
+            // make all path parameters required and valid path types.
+            for (var _j = 0, _k = Object.values(params.path.properties); _j < _k.length; _j++) {
+                var param = _k[_j];
+                if (!param.required) {
+                    param.required = true;
+                    if (param.description) {
+                        param.description += "; ";
+                    }
+                    param.description += "TODO: mark parameter as required in swagger";
+                }
+                if (param.isRef() || param.type === "object") {
+                    if (param.description) {
+                        param.description += "; ";
+                    }
+                    param.description += "TODO: cannot use " + param.type + " as path parameter";
+                    param.type = "string";
+                }
+            }
+            // add nocache query parameter if x-cache-control is specified
+            if (this.hasCacheControl(op) && !params.query.properties["nocache"]) {
+                params.query.setProperty("nocache", new openapi_ts_1.Schema("boolean"));
+            }
+            var name_3 = this.inferName(op, service);
+            var comment = op.method.toUpperCase() + " " + path_3;
+            if (op.obj.summary) {
+                comment += " - " + op.obj.summary;
+            }
+            print.comment(comment);
+            print.blank();
+            // path parameters
+            if (!params.path.isEmpty()) {
+                var pathT = name_3.pascal + "Path";
+                print.schema(params.path, pathT);
+                print.blank();
+            }
+            // query parameters
+            var queryT = name_3.pascal + "Query";
+            if (!params.query.isEmpty()) {
+                this.addImport(service, queryT);
+                print.schema(params.query, queryT);
+                print.blank();
+            }
+            // body
+            var bodyT = name_3.pascal + "Body";
+            if (!params.body.isEmpty()) {
+                this.addImport(service, bodyT);
+                print.schema(params.body, bodyT);
+                print.blank();
+            }
+            // response
+            var responseT = name_3.pascal + "Response";
+            this.addImport(service, responseT);
+            print.schema(params.response, responseT);
+            print.blank();
+            // server request
+            var requestT = name_3.pascal + "Request";
+            print.schema(this.toRequestSchema(name_3, op), requestT);
+            print.blank();
+            // method parameters
+            var method = {
+                comment: comment,
+                name: name_3.snake,
+                params: [],
+                args: ["\"" + service.name + "\"", "\"" + name_3.snake + "\"", "\"" + op.method + "\""],
+                response: responseT
+            };
+            // turn the path into a template string and add the 
+            // corresponding method parameters.
+            var pathexpr = "`" + path_3 + "`";
+            for (var _l = 0, _m = this.findPathParams(path_3); _l < _m.length; _l++) {
+                var name_4 = _m[_l];
+                var schema = params.path.properties[name_4];
+                method.params.push({
+                    name: name_4,
+                    type: openapi_ts_1.Printer.type(schema),
+                    required: true,
+                    description: schema.description
+                });
+                pathexpr = pathexpr.replace("{" + name_4 + "}", "${" + name_4 + "}");
+            }
+            method.args.push(pathexpr);
+            // if there's a body, make that a parameter too.
+            if (!params.body.isEmpty()) {
+                method.params.push({
+                    name: "body",
+                    type: bodyT,
+                    required: true,
+                    description: params.body.description
+                });
+                method.args.push("body");
+            }
+            else {
+                method.args.push("null");
+            }
+            // build the options type.
+            var options = new openapi_ts_1.Schema("empty");
+            if (!params.query.isEmpty()) {
+                var query = new openapi_ts_1.Schema(queryT);
+                if (params.query.hasRequired()) {
+                    query.required = true;
+                    options.required = true;
+                }
+                options.setProperty("query", query);
+            }
+            options.merge(new openapi_ts_1.Schema("RequestOptions"));
+            method.params.push({
+                name: "options",
+                type: openapi_ts_1.Printer.type(options),
+                required: options.required,
+                description: "additional request options"
+            });
+            method.args.push("options");
+            this.methods.push(method);
+        }
+        // close declaration
+        if (ambient) {
+            print.raw("}");
+        }
+    };
+    /**
+     * Infer the operation name from the method and parameter.
+     * These are a bunch of dirty hacks to make the generated names consistent.
+     */
+    CodeGenerator.prototype.inferName = function (op, service) {
+        var method = op.method, path = op.path;
+        var path_segments = [];
+        // use the operationId from our collection if we have one.
+        // TODO: update the swagger.json definitions so we don't need to do this.
+        var operationID = operationIDs[op.method + " " + op.path];
+        if (!operationID) {
+            operationID = op.obj.operationId;
+        }
+        if (operationID) {
+            var parts_1 = operationID.split("_");
+            if (parts_1.length > 1) {
+                // replace common operationId values with the canonical ones.
+                if (parts_1[0] === "create") {
+                    parts_1[0] = "post";
+                }
+                if (parts_1[0] === "update") {
+                    parts_1[0] = "put";
+                }
+                if (parts_1[0] === "remove") {
+                    parts_1[0] = "delete";
+                }
+                if (parts_1[0] === "find") {
+                    parts_1[0] = "get";
+                }
+                if (!(0, openapi_ts_1.isMethod)(parts_1[0])) {
+                    parts_1.unshift(method);
+                }
+                if (parts_1[0] === method) {
+                    parts_1.shift(); // remove the method
+                    if (!parts_1[0].startsWith(service.name)) {
+                        parts_1.unshift(service.name);
+                    }
+                    path_segments = parts_1;
+                }
+            }
+            if (parts_1.length > 1 && parts_1[0] === method) {
+                parts_1.shift(); // remove the method
+                if (!parts_1[0].startsWith(service.name)) {
+                    parts_1.unshift(service.name);
+                }
+                path_segments = parts_1;
+            }
+        }
+        // combined the path & method into a name.
+        if (path_segments.length === 0) {
+            if (path.endsWith(".json")) {
+                path = path.slice(0, -5);
+            }
+            path_segments = path.split("/").filter(function (segment) {
+                return segment != "" && !segment.includes("{");
+            });
+        }
+        var parts = __spreadArray([method.toLowerCase()], path_segments, true);
+        return {
+            snake: parts.join("_"),
+            pascal: parts.map(function (s) { return s.charAt(0).toUpperCase() + s.substr(1); }).join('')
+        };
+    };
+    /**
+     * Check if the any response has caching enabled.
+     */
+    CodeGenerator.prototype.hasCacheControl = function (op) {
+        var _a;
+        var responses = Object.values((_a = op.obj.responses) !== null && _a !== void 0 ? _a : {});
+        return responses.some(function (response) { return "x-cache-control" in response; });
+    };
+    /**
+     * Find all the path parameter names.
+     */
+    CodeGenerator.prototype.findPathParams = function (path) {
+        var matches = path.matchAll(/{[^}]*}/g);
+        return Array.from(matches).map(function (match) {
+            return match[0].slice(1, -1);
+        });
+    };
+    /**
+     * Create a Response type by combining the Query, Path, and Body types.
+     */
+    CodeGenerator.prototype.toRequestSchema = function (name, details) {
+        var request = new openapi_ts_1.Schema("empty");
+        if (!details.params.body.isEmpty()) {
+            var body = new openapi_ts_1.Schema(name.pascal + "Body");
+            body.required = true;
+            request.setProperty("body", body);
+        }
+        if (!details.params.query.isEmpty()) {
+            request.merge(new openapi_ts_1.Schema(name.pascal + "Query"));
+        }
+        if (!details.params.path.isEmpty()) {
+            request.merge(new openapi_ts_1.Schema(name.pascal + "Path"));
+        }
+        return request;
+    };
+    return CodeGenerator;
+}());
+exports.CodeGenerator = CodeGenerator;
+/**
+ * Main entry point.
+ */
+function main() {
+    return __awaiter(this, void 0, void 0, function () {
+        var argv, data, manifest, gen, gen, code;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    argv = (0, yargs_1["default"])((0, helpers_1.hideBin)(process.argv))
+                        .options("manifest", {
+                        type: "string",
+                        description: "manifest.json file to generate sdk from"
+                    })
+                        .options("swagger", {
+                        type: "string",
+                        description: "swagger.json file to generate interfaces from"
+                    })
+                        .options("service", {
+                        type: "string",
+                        description: "service name for generated interfaces"
+                    })
+                        .options("ambient", {
+                        type: "boolean",
+                        description: "wrap the types in a declare module directive",
+                        "default": true
+                    }).argv;
+                    if (!argv.manifest) return [3 /*break*/, 3];
+                    return [4 /*yield*/, fs_1["default"].promises.readFile(argv.manifest, "utf-8")];
+                case 1:
+                    data = _a.sent();
+                    manifest = JSON.parse(data);
+                    gen = new CodeGenerator();
+                    return [4 /*yield*/, gen.manifest(manifest)];
+                case 2:
+                    _a.sent();
+                    return [2 /*return*/];
+                case 3:
+                    if (!(argv.swagger || argv.service)) return [3 /*break*/, 5];
+                    if (!argv.swagger) {
+                        throw new Error("--swagger must be provided with --service");
+                    }
+                    if (!argv.service) {
+                        throw new Error("--service must be provided with --swagger");
+                    }
+                    gen = new CodeGenerator();
+                    return [4 /*yield*/, gen.service({
+                            name: argv.service,
+                            swagger: argv.swagger
+                        }, argv.ambient)];
+                case 4:
+                    code = _a.sent();
+                    console.log(code);
+                    return [2 /*return*/];
+                case 5: return [2 /*return*/];
+            }
+        });
+    });
+}
+main()["catch"](function (err) { return console.error(err.message); });

package/bin/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("./gen");