api 6.0.0 → 6.1.0

package/dist/cache.d.ts

@@ -3,8 +3,11 @@ import 'isomorphic-fetch';
 import Fetcher from './fetcher';
 type CacheStore = Record<string, {
     hash: string;
-    path?: string;
     original: string | OASDocument;
+    /**
+     * @deprecated Deprecated in v4.5.0 in favor of `hash`.
+     */
+    path?: string;
     title?: string;
     version?: string;
 }>;

package/dist/cli/codegen/languages/typescript.d.ts

@@ -2,19 +2,22 @@ import type Storage from '../../storage';
 import type { InstallerOptions } from '../language';
 import type Oas from 'oas';
 import type { Operation } from 'oas';
-import type { ClassDeclaration } from 'ts-morph';
+import type { ClassDeclaration, JSDocStructure, JSDocTagStructure, OptionalKind } from 'ts-morph';
 import { Project } from 'ts-morph';
 import CodeGeneratorLanguage from '../language';
 export interface TSGeneratorOptions {
-    outputJS?: boolean;
     compilerTarget?: 'cjs' | 'esm';
+    outputJS?: boolean;
 }
 interface OperationTypeHousing {
+    operation: Operation;
     types: {
         params?: false | Record<'body' | 'formData' | 'metadata', string>;
-        responses?: Record<string, string>;
+        responses?: Record<string | number, {
+            description?: string;
+            type: string;
+        }>;
     };
-    operation: Operation;
 }
 export default class TSGenerator extends CodeGeneratorLanguage {
     project: Project;
@@ -57,6 +60,17 @@ export default class TSGenerator extends CodeGeneratorLanguage {
      * @see {@link https://npm.im/json-schema-to-ts}
      */
     createTypesFile(): import("ts-morph").SourceFile;
+    /**
+     * Add a new JSDoc `@tag` to an existing docblock.
+     *
+     */
+    static addTagToDocblock(docblock: OptionalKind<JSDocStructure>, tag: OptionalKind<JSDocTagStructure>): {
+        tags: OptionalKind<JSDocTagStructure>[];
+        description?: string | import("ts-morph").WriterFunction;
+        leadingTrivia?: string | import("ts-morph").WriterFunction | (string | import("ts-morph").WriterFunction)[];
+        trailingTrivia?: string | import("ts-morph").WriterFunction | (string | import("ts-morph").WriterFunction)[];
+        kind?: import("ts-morph").StructureKind.JSDoc;
+    };
     /**
      * Create operation accessors on the SDK.
      *
@@ -83,7 +97,10 @@ export default class TSGenerator extends CodeGeneratorLanguage {
      *
      */
     prepareResponseTypesForOperation(operation: Operation, operationId: string): {
-        [x: string]: string;
+        [x: string]: {
+            type: string;
+            description: any;
+        };
     };
     /**
      * Add a given schema into our schema dataset that we'll be be exporting as types.

package/dist/cli/codegen/languages/typescript.js

@@ -471,6 +471,16 @@ var TSGenerator = /** @class */ (function (_super) {
         });
         return sourceFile;
     };
+    /**
+     * Add a new JSDoc `@tag` to an existing docblock.
+     *
+     */
+    TSGenerator.addTagToDocblock = function (docblock, tag) {
+        var _a;
+        var tags = (_a = docblock.tags) !== null && _a !== void 0 ? _a : [];
+        tags.push(tag);
+        return __assign(__assign({}, docblock), { tags: tags });
+    };
     /**
      * Create operation accessors on the SDK.
      *
@@ -495,7 +505,10 @@ var TSGenerator = /** @class */ (function (_super) {
                 return writer;
             };
             if (summary && description) {
-                docblock.tags = [{ tagName: 'summary', text: (0, util_1.docblockEscape)((0, util_1.wordWrap)(summary)) }];
+                docblock = TSGenerator.addTagToDocblock(docblock, {
+                    tagName: 'summary',
+                    text: (0, util_1.docblockEscape)((0, util_1.wordWrap)(summary))
+                });
             }
         }
         var hasOptionalBody = false;
@@ -523,9 +536,9 @@ var TSGenerator = /** @class */ (function (_super) {
         }
         var returnType = 'Promise<FetchResponse<number, unknown>>';
         if (responseTypes) {
-            returnType = "Promise<".concat(Object.entries(responseTypes)
+            var returnTypes = Object.entries(responseTypes)
                 .map(function (_a) {
-                var status = _a[0], responseType = _a[1];
+                var status = _a[0], _b = _a[1], responseDescription = _b.description, responseType = _b.type;
                 if (status.toLowerCase() === 'default') {
                     return "FetchResponse<number, ".concat(responseType, ">");
                 }
@@ -536,17 +549,42 @@ var TSGenerator = /** @class */ (function (_super) {
                         // it and should instead fall back to treating it as an unknown number.
                         return "FetchResponse<number, ".concat(responseType, ">");
                     }
+                    if (Number(statusPrefix) >= 4) {
+                        docblock = TSGenerator.addTagToDocblock(docblock, {
+                            tagName: 'throws',
+                            text: "FetchError<".concat(status, ", ").concat(responseType, ">").concat(responseDescription ? (0, util_1.docblockEscape)((0, util_1.wordWrap)(" ".concat(responseDescription))) : '')
+                        });
+                        return false;
+                    }
                     _this.usesHTTPMethodRangeInterface = true;
                     return "FetchResponse<HTTPMethodRange<".concat(statusPrefix, "00, ").concat(statusPrefix, "99>, ").concat(responseType, ">");
                 }
+                // 400 and 500 status code families are thrown as exceptions so adding them as a possible
+                // return type isn't valid.
+                if (Number(status) >= 400) {
+                    docblock = TSGenerator.addTagToDocblock(docblock, {
+                        tagName: 'throws',
+                        text: "FetchError<".concat(status, ", ").concat(responseType, ">").concat(responseDescription ? (0, util_1.docblockEscape)((0, util_1.wordWrap)(" ".concat(responseDescription))) : '')
+                    });
+                    return false;
+                }
                 return "FetchResponse<".concat(status, ", ").concat(responseType, ">");
             })
-                .join(' | '), ">");
+                .filter(Boolean)
+                .join(' | ');
+            // If all of our documented responses are for error status codes then all we can document for
+            // anything else that might happen is `unknown`.
+            returnType = "Promise<".concat(returnTypes.length ? returnTypes : 'FetchResponse<number, unknown>', ">");
         }
+        var shouldAddAltTypedOverloads = Object.keys(parameters).length === 2 && hasOptionalBody && !hasOptionalMetadata;
         var operationIdAccessor = this.sdk.addMethod({
             name: operationId,
             returnType: returnType,
-            docs: Object.keys(docblock).length ? [docblock] : null,
+            // If we're going to be creating typed method overloads for optional body an metadata handling
+            // we should only add a docblock to the first overload we create because IDE Intellisense will
+            // always use that and adding a docblock to all three will bloat the SDK with unused and
+            // unsurfaced method documentation.
+            docs: shouldAddAltTypedOverloads ? null : Object.keys(docblock).length ? [docblock] : null,
             statements: function (writer) {
                 /**
                  * @example return this.core.fetch('/pet/findByStatus', 'get', body, metadata);
@@ -576,10 +614,6 @@ var TSGenerator = /** @class */ (function (_super) {
         // If we have both body and metadata parameters but only body is optional we need to create
         // a couple function overloads as Typescript doesn't let us have an optional method parameter
         // come before one that's required.
-        //
-        // None of these accessor overloads will receive a docblock because the original will have
-        // that covered.
-        var shouldAddAltTypedOverloads = Object.keys(parameters).length === 2 && hasOptionalBody && !hasOptionalMetadata;
         if (shouldAddAltTypedOverloads) {
             // Create an overload that has both `body` and `metadata` parameters as required.
             operationIdAccessor.addOverload({
@@ -593,8 +627,7 @@ var TSGenerator = /** @class */ (function (_super) {
             // Create an overload that just has a single `metadata` parameter.
             operationIdAccessor.addOverload({
                 parameters: [__assign({}, parameters.metadata)],
-                returnType: returnType,
-                docs: Object.keys(docblock).length ? [docblock] : null
+                returnType: returnType
             });
             // Create an overload that has both `body` and `metadata` parameters as optional. Even though
             // our `metadata` parameter is actually required for this operation this is the only way we're
@@ -746,7 +779,7 @@ var TSGenerator = /** @class */ (function (_super) {
         var res = Object.entries(schemas)
             .map(function (_a) {
             var _b;
-            var status = _a[0], schema = _a[1].schema;
+            var status = _a[0], _c = _a[1], description = _c.description, schema = _c.schema;
             var typeName;
             if (typeof schema === 'string' && schema.startsWith('::convert::')) {
                 // If this schema is a string and has our conversion prefix then we've already created
@@ -763,7 +796,10 @@ var TSGenerator = /** @class */ (function (_super) {
             return _b = {},
                 // Types are prefixed with `types.` because that's how we're importing them from
                 // `types.d.ts`.
-                _b[status] = "types.".concat(typeName),
+                _b[status] = {
+                    type: "types.".concat(typeName),
+                    description: description
+                },
                 _b;
         })
             .reduce(function (prev, next) { return Object.assign(prev, next); }, {});

package/dist/cli/commands/install.js

@@ -43,7 +43,6 @@ var commander_1 = require("commander");
 var figures_1 = __importDefault(require("figures"));
 var oas_1 = __importDefault(require("oas"));
 var ora_1 = __importDefault(require("ora"));
-var validate_npm_package_name_1 = __importDefault(require("validate-npm-package-name"));
 var fetcher_1 = __importDefault(require("../../fetcher"));
 var codegen_1 = __importDefault(require("../codegen"));
 var prompt_1 = __importDefault(require("../lib/prompt"));
@@ -55,6 +54,7 @@ cmd
     .name('install')
     .description('install an API SDK into your codebase')
     .argument('<uri>', 'an API to install')
+    .option('-i, --identifier <identifier>', 'API identifier (eg. `@api/petstore`)')
     .addOption(new commander_1.Option('-l, --lang <language>', 'SDK language').choices([
     'js',
     'js-cjs',
@@ -107,10 +107,17 @@ cmd
                     // @todo
                     // logger(`It looks like you already have this API installed. Would you like to update it?`);
                 }
-                if (!fetcher_1["default"].isAPIRegistryUUID(uri)) return [3 /*break*/, 6];
+                if (!options.identifier) return [3 /*break*/, 6];
+                // `Storage.isIdentifierValid` will throw an exception if an identifier is invalid.
+                if (storage_1["default"].isIdentifierValid(options.identifier)) {
+                    identifier = options.identifier;
+                }
+                return [3 /*break*/, 9];
+            case 6:
+                if (!fetcher_1["default"].isAPIRegistryUUID(uri)) return [3 /*break*/, 7];
                 identifier = fetcher_1["default"].getProjectPrefixFromRegistryUUID(uri);
-                return [3 /*break*/, 8];
-            case 6: return [4 /*yield*/, (0, prompt_1["default"])({
+                return [3 /*break*/, 9];
+            case 7: return [4 /*yield*/, (0, prompt_1["default"])({
                     type: 'text',
                     name: 'value',
                     message: 'What would you like to identify this API as? This will be how you import the SDK. (e.g. entering `petstore` would result in `@api/petstore`)',
@@ -118,23 +125,18 @@ cmd
                         if (!value) {
                             return false;
                         }
-                        // Is this identifier already in storage?
-                        if (storage_1["default"].isInLockFile({ identifier: value })) {
-                            return "\"".concat(value, "\" is already taken in your `.api/` directory. Please enter another identifier.");
+                        try {
+                            return storage_1["default"].isIdentifierValid(value, true);
                         }
-                        var isValidForNPM = (0, validate_npm_package_name_1["default"])("@api/".concat(value));
-                        if (!isValidForNPM.validForNewPackages) {
-                            // `prompts` doesn't support surfacing multiple errors in a `validate` call so we can
-                            // only surface the first to the user.
-                            return isValidForNPM.errors[0];
+                        catch (err) {
+                            return err.message;
                         }
-                        return true;
                     }
                 })];
-            case 7:
-                (identifier = (_a.sent()).value);
-                _a.label = 8;
             case 8:
+                (identifier = (_a.sent()).value);
+                _a.label = 9;
+            case 9:
                 if (!identifier) {
                     (0, logger_1["default"])('You must tell us what you would like to identify this API as in order to install it.', true);
                     process.exit(1);
@@ -153,7 +155,7 @@ cmd
                         (0, logger_1["default"])(err.message, true);
                         process.exit(1);
                     })];
-            case 9:
+            case 10:
                 oas = _a.sent();
                 // @todo look for a prettier config and if we find one ask them if we should use it
                 spinner = (0, ora_1["default"])('Generating your SDK').start();
@@ -169,7 +171,7 @@ cmd
                         (0, logger_1["default"])(err.message, true);
                         process.exit(1);
                     })];
-            case 10:
+            case 11:
                 sdkSource = _a.sent();
                 spinner = (0, ora_1["default"])('Saving your SDK into your codebase').start();
                 return [4 /*yield*/, storage
@@ -182,15 +184,15 @@ cmd
                         (0, logger_1["default"])(err.message, true);
                         process.exit(1);
                     })];
-            case 11:
+            case 12:
                 _a.sent();
-                if (!generator.hasRequiredPackages()) return [3 /*break*/, 17];
+                if (!generator.hasRequiredPackages()) return [3 /*break*/, 18];
                 (0, logger_1["default"])("".concat(figures_1["default"].warning, " This generator requires some packages to be installed alongside it:"));
                 Object.entries(generator.requiredPackages).forEach(function (_a) {
                     var pkg = _a[0], pkgInfo = _a[1];
                     (0, logger_1["default"])("  ".concat(figures_1["default"].pointerSmall, " ").concat(pkg, ": ").concat(pkgInfo.reason, " ").concat(pkgInfo.url));
                 });
-                if (!!options.yes) return [3 /*break*/, 13];
+                if (!!options.yes) return [3 /*break*/, 14];
                 return [4 /*yield*/, (0, prompt_1["default"])({
                         type: 'confirm',
                         name: 'value',
@@ -204,27 +206,27 @@ cmd
                             process.exit(1);
                         }
                     })];
-            case 12:
-                _a.sent();
-                _a.label = 13;
             case 13:
-                spinner = (0, ora_1["default"])('Installing required packages').start();
+                _a.sent();
                 _a.label = 14;
             case 14:
-                _a.trys.push([14, 16, , 17]);
-                return [4 /*yield*/, generator.installer(storage)];
+                spinner = (0, ora_1["default"])('Installing required packages').start();
+                _a.label = 15;
             case 15:
+                _a.trys.push([15, 17, , 18]);
+                return [4 /*yield*/, generator.installer(storage)];
+            case 16:
                 _a.sent();
                 spinner.succeed(spinner.text);
-                return [3 /*break*/, 17];
-            case 16:
+                return [3 /*break*/, 18];
+            case 17:
                 err_1 = _a.sent();
                 // @todo cleanup installed files
                 spinner.fail(spinner.text);
                 (0, logger_1["default"])(err_1.message, true);
                 process.exit(1);
-                return [3 /*break*/, 17];
-            case 17:
+                return [3 /*break*/, 18];
+            case 18:
                 (0, logger_1["default"])('🚀 All done!');
                 return [2 /*return*/];
         }

package/dist/cli/storage.d.ts

@@ -23,6 +23,7 @@ export default class Storage {
     static getDefaultLockfile(): Lockfile;
     static generateIntegrityHash(definition: OASDocument): string;
     static getLockfile(): Lockfile;
+    static isIdentifierValid(identifier: string, prefixWithAPINamespace?: boolean): boolean;
     static isInLockFile(search: {
         identifier?: string;
         source?: string;
@@ -61,17 +62,16 @@ export default class Storage {
      *         ├── openapi.json
      *         └── package.json
      *
-     * @param spec
      */
     save(spec: OASDocument): OASDocument;
 }
 export interface Lockfile {
+    apis: LockfileAPI[];
     /**
      * The `api.json` schema version. This will only ever change if we introduce breaking changes to
      * this store.
      */
     version: '1.0';
-    apis: LockfileAPI[];
 }
 export interface LockfileAPI {
     /**
@@ -82,13 +82,11 @@ export interface LockfileAPI {
      */
     identifier: string;
     /**
-     * The original source that was used to generate the SDK with.
+     * The version of `api` that was used to install this SDK.
      *
-     * @example https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
-     * @example ./petstore.json
-     * @example @developers/v2.0#nysezql0wwo236
+     * @example 5.0.0
      */
-    source: string;
+    installerVersion: string;
     /**
      * An integrity hash that will be used to determine on `npx api update` calls if the API has
      * changed since the SDK was last generated.
@@ -97,9 +95,11 @@ export interface LockfileAPI {
      */
     integrity: string;
     /**
-     * The version of `api` that was used to install this SDK.
+     * The original source that was used to generate the SDK with.
      *
-     * @example 5.0.0
+     * @example https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
+     * @example ./petstore.json
+     * @example @developers/v2.0#nysezql0wwo236
      */
-    installerVersion: string;
+    source: string;
 }

package/dist/cli/storage.js

@@ -43,6 +43,7 @@ var fs_1 = __importDefault(require("fs"));
 var path_1 = __importDefault(require("path"));
 var make_dir_1 = __importDefault(require("make-dir"));
 var ssri_1 = __importDefault(require("ssri"));
+var validate_npm_package_name_1 = __importDefault(require("validate-npm-package-name"));
 var fetcher_1 = __importDefault(require("../fetcher"));
 var packageInfo_1 = require("../packageInfo");
 var Storage = /** @class */ (function () {
@@ -128,6 +129,19 @@ var Storage = /** @class */ (function () {
         }
         return Storage.lockfile;
     };
+    Storage.isIdentifierValid = function (identifier, prefixWithAPINamespace) {
+        // Is this identifier already in storage?
+        if (Storage.isInLockFile({ identifier: identifier })) {
+            throw new Error("\"".concat(identifier, "\" is already taken in your `.api/` directory. Please try another identifier."));
+        }
+        var isValidForNPM = (0, validate_npm_package_name_1["default"])(prefixWithAPINamespace ? "@api/".concat(identifier) : identifier);
+        if (!isValidForNPM.validForNewPackages) {
+            // `prompts` doesn't support surfacing multiple errors in a `validate` call so we can only
+            // surface the first to the user.
+            throw new Error("Identifier cannot be used for an NPM package: ".concat(isValidForNPM.errors[0]));
+        }
+        return true;
+    };
     Storage.isInLockFile = function (search) {
         // Because this method may run before we initialize a new storage object we should make sure
         // that we have a storage directory present.
@@ -221,7 +235,6 @@ var Storage = /** @class */ (function () {
      *         ├── openapi.json
      *         └── package.json
      *
-     * @param spec
      */
     Storage.prototype.save = function (spec) {
         if (!this.identifier) {

package/dist/core/errors/fetchError.d.ts

@@ -1,12 +1,12 @@
-declare class FetchError extends Error {
+declare class FetchError<Status = number, Data = unknown> extends Error {
     /** HTTP Status */
-    status: number;
+    status: Status;
     /** The content of the response. */
-    data: unknown;
+    data: Data;
     /** The Headers of the response. */
     headers: Headers;
     /** The raw `Response` object. */
     res: Response;
-    constructor(status: number, data: unknown, headers: Headers, res: Response);
+    constructor(status: Status, data: Data, headers: Headers, res: Response);
 }
 export default FetchError;

package/dist/core/getJSONSchemaDefaults.d.ts

@@ -8,7 +8,6 @@ import type { SchemaWrapper } from 'oas/dist/operation/get-parameters-as-json-sc
  *
  * @todo This is a good candidate to be moved into a core `oas` library method.
  * @see {@link https://github.com/mdornseif/json-schema-default}
- * @param jsonSchemas
  */
 export default function getJSONSchemaDefaults(jsonSchemas: SchemaWrapper[]): {
     [x: string]: Record<string, unknown>;

package/dist/core/getJSONSchemaDefaults.js

@@ -13,7 +13,6 @@ var json_schema_traverse_1 = __importDefault(require("json-schema-traverse"));
  *
  * @todo This is a good candidate to be moved into a core `oas` library method.
  * @see {@link https://github.com/mdornseif/json-schema-default}
- * @param jsonSchemas
  */
 function getJSONSchemaDefaults(jsonSchemas) {
     return jsonSchemas

package/dist/core/index.d.ts

@@ -16,9 +16,9 @@ export interface ConfigOptions {
 }
 export interface FetchResponse<status, data> {
     data: data;
-    status: status;
     headers: Headers;
     res: Response;
+    status: status;
 }
 type Enumerate<N extends number, Acc extends number[] = []> = Acc['length'] extends N ? Acc[number] : Enumerate<N, [...Acc, Acc['length']]>;
 export type HTTPMethodRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F>>;

package/dist/core/prepareAuth.d.ts

@@ -1,5 +1,5 @@
 import type { Operation } from 'oas';
 export default function prepareAuth(authKey: (number | string)[], operation: Operation): Record<string, string | number | {
-    user: string | number;
     pass: string | number;
+    user: string | number;
 }>;

package/dist/core/prepareServer.d.ts

@@ -3,9 +3,6 @@ import type Oas from 'oas';
  * With an SDK server config and an instance of OAS we should extract and prepare the server and
  * any server variables to be supplied to `@readme/oas-to-har`.
  *
- * @param spec
- * @param url
- * @param variables
  */
 export default function prepareServer(spec: Oas, url: string, variables?: Record<string, string | number>): false | {
     selected: number;

package/dist/core/prepareServer.js

@@ -10,9 +10,6 @@ function stripTrailingSlash(url) {
  * With an SDK server config and an instance of OAS we should extract and prepare the server and
  * any server variables to be supplied to `@readme/oas-to-har`.
  *
- * @param spec
- * @param url
- * @param variables
  */
 function prepareServer(spec, url, variables) {
     if (variables === void 0) { variables = {}; }

package/dist/index.js

@@ -70,7 +70,6 @@ var Sdk = /** @class */ (function () {
          * Create dynamic accessors for every operation with a defined operation ID. If an operation
          * does not have an operation ID it can be accessed by its `.method('/path')` accessor instead.
          *
-         * @param spec
          */
         function loadOperations(spec) {
             return Object.entries(spec.getPaths())

package/dist/packageInfo.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "api";
-export declare const PACKAGE_VERSION = "6.0.0";
+export declare const PACKAGE_VERSION = "6.1.0";

package/dist/packageInfo.js

@@ -3,4 +3,4 @@ exports.__esModule = true;
 exports.PACKAGE_VERSION = exports.PACKAGE_NAME = void 0;
 // This file is automatically updated by the build script.
 exports.PACKAGE_NAME = 'api';
-exports.PACKAGE_VERSION = '6.0.0';
+exports.PACKAGE_VERSION = '6.1.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Magical SDK generation from an OpenAPI definition 🪄",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,8 +12,8 @@
     "debug:bin": "node -r ts-node/register src/bin.ts",
     "prebuild": "rm -rf dist/; npm run version",
     "prepack": "npm run build",
-    "test": "nyc mocha $(find test -name '*.test.ts' -not -path '*/smoketest.test.ts')",
-    "test:smoke": "npx mocha test/cli/codegen/languages/typescript/smoketest.test.ts",
+    "test": "jest --coverage $(find test -name '*.test.ts' -not -path '*/smoketest.test.ts')",
+    "test:smoke": "npx jest test/cli/codegen/languages/typescript/smoketest.test.ts",
     "version": "node -p \"'// This file is automatically updated by the build script.\\nexport const PACKAGE_NAME = \\'' + require('./package.json').name + '\\';\\nexport const PACKAGE_VERSION = \\'' + require('./package.json').version + '\\';'\" > src/packageInfo.ts; git add src/packageInfo.ts"
   },
   "repository": {
@@ -74,39 +74,28 @@
   "devDependencies": {
     "@readme/oas-examples": "^5.9.0",
     "@types/caseless": "^0.12.2",
-    "@types/chai": "^4.3.4",
     "@types/find-cache-dir": "^3.2.1",
+    "@types/jest": "^29.5.2",
     "@types/js-yaml": "^4.0.5",
     "@types/lodash.camelcase": "^4.3.7",
     "@types/lodash.deburr": "^4.1.7",
     "@types/lodash.merge": "^4.6.7",
     "@types/lodash.setwith": "^4.3.7",
     "@types/lodash.startcase": "^4.4.7",
-    "@types/mocha": "^10.0.1",
     "@types/prettier": "^2.7.2",
     "@types/prompts": "^2.4.2",
     "@types/semver": "^7.3.13",
-    "@types/sinon-chai": "^3.2.9",
     "@types/ssri": "^7.1.1",
     "@types/validate-npm-package-name": "^4.0.0",
-    "chai": "^4.3.7",
     "fetch-mock": "^9.11.0",
-    "mocha": "^10.1.0",
-    "mock-require": "^3.0.3",
-    "nyc": "^15.1.0",
+    "jest": "^29.6.1",
+    "jest-extended": "^4.0.0",
     "oas-normalize": "^8.3.2",
-    "sinon": "^15.0.0",
-    "sinon-chai": "^3.7.0",
+    "ts-jest": "^29.1.1",
     "type-fest": "^3.5.4",
     "typescript": "^4.9.5",
     "unique-temp-dir": "^1.0.0"
   },
   "prettier": "@readme/eslint-config/prettier",
-  "nyc": {
-    "exclude": [
-      "dist/",
-      "test/"
-    ]
-  },
-  "gitHead": "9759db4c067baf3928ad3a9d76b4965658955d78"
+  "gitHead": "244093f2ad00e5ea527420f49bdb541bc2095806"
 }

package/src/cache.ts

@@ -16,8 +16,11 @@ type CacheStore = Record<
   string,
   {
     hash: string;
-    path?: string; // Deprecated in v4.5.0 in favor of `hash`.
     original: string | OASDocument;
+    /**
+     * @deprecated Deprecated in v4.5.0 in favor of `hash`.
+     */
+    path?: string;
     title?: string;
     version?: string;
   }

package/src/cli/codegen/languages/typescript.ts

@@ -3,7 +3,13 @@ import type { InstallerOptions } from '../language';
 import type Oas from 'oas';
 import type { Operation } from 'oas';
 import type { HttpMethods, SchemaObject } from 'oas/dist/rmoas.types';
-import type { ClassDeclaration, JSDocStructure, OptionalKind, ParameterDeclarationStructure } from 'ts-morph';
+import type {
+  ClassDeclaration,
+  JSDocStructure,
+  JSDocTagStructure,
+  OptionalKind,
+  ParameterDeclarationStructure,
+} from 'ts-morph';
 import type { PackageJson } from 'type-fest';
 
 import fs from 'fs';
@@ -20,16 +26,22 @@ import CodeGeneratorLanguage from '../language';
 import { docblockEscape, formatter, generateTypeName, wordWrap } from './typescript/util';
 
 export interface TSGeneratorOptions {
-  outputJS?: boolean;
   compilerTarget?: 'cjs' | 'esm';
+  outputJS?: boolean;
 }
 
 interface OperationTypeHousing {
+  operation: Operation;
   types: {
     params?: false | Record<'body' | 'formData' | 'metadata', string>;
-    responses?: Record<string, string>;
+    responses?: Record<
+      string | number,
+      {
+        description?: string;
+        type: string;
+      }
+    >;
   };
-  operation: Operation;
 }
 
 export default class TSGenerator extends CodeGeneratorLanguage {
@@ -60,7 +72,7 @@ export default class TSGenerator extends CodeGeneratorLanguage {
   usesHTTPMethodRangeInterface = false;
 
   constructor(spec: Oas, specPath: string, identifier: string, opts: TSGeneratorOptions = {}) {
-    const options: { outputJS: boolean; compilerTarget: 'cjs' | 'esm' } = {
+    const options: { compilerTarget: 'cjs' | 'esm'; outputJS: boolean } = {
       outputJS: false,
       compilerTarget: 'cjs',
       ...opts,
@@ -502,6 +514,20 @@ sdk.server('https://eu.api.example.com/v14');`)
     return sourceFile;
   }
 
+  /**
+   * Add a new JSDoc `@tag` to an existing docblock.
+   *
+   */
+  static addTagToDocblock(docblock: OptionalKind<JSDocStructure>, tag: OptionalKind<JSDocTagStructure>) {
+    const tags = docblock.tags ?? [];
+    tags.push(tag);
+
+    return {
+      ...docblock,
+      tags,
+    };
+  }
+
   /**
    * Create operation accessors on the SDK.
    *
@@ -512,7 +538,7 @@ sdk.server('https://eu.api.example.com/v14');`)
     paramTypes?: OperationTypeHousing['types']['params'],
     responseTypes?: OperationTypeHousing['types']['responses']
   ) {
-    const docblock: OptionalKind<JSDocStructure> = {};
+    let docblock: OptionalKind<JSDocStructure> = {};
     const summary = operation.getSummary();
     const description = operation.getDescription();
     if (summary || description) {
@@ -531,7 +557,10 @@ sdk.server('https://eu.api.example.com/v14');`)
       };
 
       if (summary && description) {
-        docblock.tags = [{ tagName: 'summary', text: docblockEscape(wordWrap(summary)) }];
+        docblock = TSGenerator.addTagToDocblock(docblock, {
+          tagName: 'summary',
+          text: docblockEscape(wordWrap(summary)),
+        });
       }
     }
 
@@ -568,8 +597,8 @@ sdk.server('https://eu.api.example.com/v14');`)
 
     let returnType = 'Promise<FetchResponse<number, unknown>>';
     if (responseTypes) {
-      returnType = `Promise<${Object.entries(responseTypes)
-        .map(([status, responseType]) => {
+      const returnTypes = Object.entries(responseTypes)
+        .map(([status, { description: responseDescription, type: responseType }]) => {
           if (status.toLowerCase() === 'default') {
             return `FetchResponse<number, ${responseType}>`;
           } else if (status.length === 3 && status.toUpperCase().endsWith('XX')) {
@@ -580,19 +609,54 @@ sdk.server('https://eu.api.example.com/v14');`)
               return `FetchResponse<number, ${responseType}>`;
             }
 
+            if (Number(statusPrefix) >= 4) {
+              docblock = TSGenerator.addTagToDocblock(docblock, {
+                tagName: 'throws',
+                text: `FetchError<${status}, ${responseType}>${
+                  responseDescription ? docblockEscape(wordWrap(` ${responseDescription}`)) : ''
+                }`,
+              });
+
+              return false;
+            }
+
             this.usesHTTPMethodRangeInterface = true;
             return `FetchResponse<HTTPMethodRange<${statusPrefix}00, ${statusPrefix}99>, ${responseType}>`;
           }
 
+          // 400 and 500 status code families are thrown as exceptions so adding them as a possible
+          // return type isn't valid.
+          if (Number(status) >= 400) {
+            docblock = TSGenerator.addTagToDocblock(docblock, {
+              tagName: 'throws',
+              text: `FetchError<${status}, ${responseType}>${
+                responseDescription ? docblockEscape(wordWrap(` ${responseDescription}`)) : ''
+              }`,
+            });
+
+            return false;
+          }
+
           return `FetchResponse<${status}, ${responseType}>`;
         })
-        .join(' | ')}>`;
+        .filter(Boolean)
+        .join(' | ');
+
+      // If all of our documented responses are for error status codes then all we can document for
+      // anything else that might happen is `unknown`.
+      returnType = `Promise<${returnTypes.length ? returnTypes : 'FetchResponse<number, unknown>'}>`;
     }
 
+    const shouldAddAltTypedOverloads = Object.keys(parameters).length === 2 && hasOptionalBody && !hasOptionalMetadata;
     const operationIdAccessor = this.sdk.addMethod({
       name: operationId,
       returnType,
-      docs: Object.keys(docblock).length ? [docblock] : null,
+
+      // If we're going to be creating typed method overloads for optional body an metadata handling
+      // we should only add a docblock to the first overload we create because IDE Intellisense will
+      // always use that and adding a docblock to all three will bloat the SDK with unused and
+      // unsurfaced method documentation.
+      docs: shouldAddAltTypedOverloads ? null : Object.keys(docblock).length ? [docblock] : null,
       statements: writer => {
         /**
          * @example return this.core.fetch('/pet/findByStatus', 'get', body, metadata);
@@ -626,10 +690,6 @@ sdk.server('https://eu.api.example.com/v14');`)
     // If we have both body and metadata parameters but only body is optional we need to create
     // a couple function overloads as Typescript doesn't let us have an optional method parameter
     // come before one that's required.
-    //
-    // None of these accessor overloads will receive a docblock because the original will have
-    // that covered.
-    const shouldAddAltTypedOverloads = Object.keys(parameters).length === 2 && hasOptionalBody && !hasOptionalMetadata;
     if (shouldAddAltTypedOverloads) {
       // Create an overload that has both `body` and `metadata` parameters as required.
       operationIdAccessor.addOverload({
@@ -645,7 +705,6 @@ sdk.server('https://eu.api.example.com/v14');`)
       operationIdAccessor.addOverload({
         parameters: [{ ...parameters.metadata }],
         returnType,
-        docs: Object.keys(docblock).length ? [docblock] : null,
       });
 
       // Create an overload that has both `body` and `metadata` parameters as optional. Even though
@@ -807,7 +866,7 @@ sdk.server('https://eu.api.example.com/v14');`)
       .reduce((prev, next) => Object.assign(prev, next));
 
     const res = Object.entries(schemas)
-      .map(([status, { schema }]) => {
+      .map(([status, { description, schema }]) => {
         let typeName;
 
         if (typeof schema === 'string' && schema.startsWith('::convert::')) {
@@ -826,7 +885,10 @@ sdk.server('https://eu.api.example.com/v14');`)
         return {
           // Types are prefixed with `types.` because that's how we're importing them from
           // `types.d.ts`.
-          [status]: `types.${typeName}`,
+          [status]: {
+            type: `types.${typeName}`,
+            description,
+          },
         };
       })
       .reduce((prev, next) => Object.assign(prev, next), {});

package/src/cli/commands/install.ts

@@ -4,7 +4,6 @@ import { Command, Option } from 'commander';
 import figures from 'figures';
 import Oas from 'oas';
 import ora from 'ora';
-import validateNPMPackageName from 'validate-npm-package-name';
 
 import Fetcher from '../../fetcher';
 import codegen from '../codegen';
@@ -18,6 +17,7 @@ cmd
   .name('install')
   .description('install an API SDK into your codebase')
   .argument('<uri>', 'an API to install')
+  .option('-i, --identifier <identifier>', 'API identifier (eg. `@api/petstore`)')
   .addOption(
     new Option('-l, --lang <language>', 'SDK language').choices([
       'js', // User generally wants JS, we'll prompt if they want CJS or ESM files.
@@ -27,7 +27,7 @@ cmd
     ])
   )
   .addOption(new Option('-y, --yes', 'Automatically answer "yes" to any prompts printed'))
-  .action(async (uri: string, options: { lang: string; yes?: boolean }) => {
+  .action(async (uri: string, options: { identifier?: string; lang: string; yes?: boolean }) => {
     let language: SupportedLanguages;
     if (options.lang) {
       language = options.lang as SupportedLanguages;
@@ -69,7 +69,12 @@ cmd
     }
 
     let identifier;
-    if (Fetcher.isAPIRegistryUUID(uri)) {
+    if (options.identifier) {
+      // `Storage.isIdentifierValid` will throw an exception if an identifier is invalid.
+      if (Storage.isIdentifierValid(options.identifier)) {
+        identifier = options.identifier;
+      }
+    } else if (Fetcher.isAPIRegistryUUID(uri)) {
       identifier = Fetcher.getProjectPrefixFromRegistryUUID(uri);
     } else {
       ({ value: identifier } = await promptTerminal({
@@ -82,19 +87,11 @@ cmd
             return false;
           }
 
-          // Is this identifier already in storage?
-          if (Storage.isInLockFile({ identifier: value })) {
-            return `"${value}" is already taken in your \`.api/\` directory. Please enter another identifier.`;
-          }
-
-          const isValidForNPM = validateNPMPackageName(`@api/${value}`);
-          if (!isValidForNPM.validForNewPackages) {
-            // `prompts` doesn't support surfacing multiple errors in a `validate` call so we can
-            // only surface the first to the user.
-            return isValidForNPM.errors[0];
+          try {
+            return Storage.isIdentifierValid(value, true);
+          } catch (err) {
+            return err.message;
           }
-
-          return true;
         },
       }));
     }

package/src/cli/storage.ts

@@ -5,6 +5,7 @@ import path from 'path';
 
 import makeDir from 'make-dir';
 import ssri from 'ssri';
+import validateNPMPackageName from 'validate-npm-package-name';
 
 import Fetcher from '../fetcher';
 import { PACKAGE_VERSION } from '../packageInfo';
@@ -105,6 +106,22 @@ export default class Storage {
     return Storage.lockfile;
   }
 
+  static isIdentifierValid(identifier: string, prefixWithAPINamespace?: boolean) {
+    // Is this identifier already in storage?
+    if (Storage.isInLockFile({ identifier })) {
+      throw new Error(`"${identifier}" is already taken in your \`.api/\` directory. Please try another identifier.`);
+    }
+
+    const isValidForNPM = validateNPMPackageName(prefixWithAPINamespace ? `@api/${identifier}` : identifier);
+    if (!isValidForNPM.validForNewPackages) {
+      // `prompts` doesn't support surfacing multiple errors in a `validate` call so we can only
+      // surface the first to the user.
+      throw new Error(`Identifier cannot be used for an NPM package: ${isValidForNPM.errors[0]}`);
+    }
+
+    return true;
+  }
+
   static isInLockFile(search: { identifier?: string; source?: string }) {
     // Because this method may run before we initialize a new storage object we should make sure
     // that we have a storage directory present.
@@ -207,7 +224,6 @@ export default class Storage {
    *         ├── openapi.json
    *         └── package.json
    *
-   * @param spec
    */
   save(spec: OASDocument) {
     if (!this.identifier) {
@@ -254,12 +270,13 @@ export default class Storage {
 }
 
 export interface Lockfile {
+  apis: LockfileAPI[];
+
   /**
    * The `api.json` schema version. This will only ever change if we introduce breaking changes to
    * this store.
    */
   version: '1.0';
-  apis: LockfileAPI[];
 }
 
 export interface LockfileAPI {
@@ -272,13 +289,11 @@ export interface LockfileAPI {
   identifier: string;
 
   /**
-   * The original source that was used to generate the SDK with.
+   * The version of `api` that was used to install this SDK.
    *
-   * @example https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
-   * @example ./petstore.json
-   * @example @developers/v2.0#nysezql0wwo236
+   * @example 5.0.0
    */
-  source: string;
+  installerVersion: string;
 
   /**
    * An integrity hash that will be used to determine on `npx api update` calls if the API has
@@ -289,9 +304,11 @@ export interface LockfileAPI {
   integrity: string;
 
   /**
-   * The version of `api` that was used to install this SDK.
+   * The original source that was used to generate the SDK with.
    *
-   * @example 5.0.0
+   * @example https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
+   * @example ./petstore.json
+   * @example @developers/v2.0#nysezql0wwo236
    */
-  installerVersion: string;
+  source: string;
 }

package/src/core/errors/fetchError.ts

@@ -1,9 +1,9 @@
-class FetchError extends Error {
+class FetchError<Status = number, Data = unknown> extends Error {
   /** HTTP Status */
-  status: number;
+  status: Status;
 
   /** The content of the response. */
-  data: unknown;
+  data: Data;
 
   /** The Headers of the response. */
   headers: Headers;
@@ -11,7 +11,7 @@ class FetchError extends Error {
   /** The raw `Response` object. */
   res: Response;
 
-  constructor(status: number, data: unknown, headers: Headers, res: Response) {
+  constructor(status: Status, data: Data, headers: Headers, res: Response) {
     super(res.statusText);
 
     this.name = 'FetchError';

package/src/core/getJSONSchemaDefaults.ts

@@ -12,7 +12,6 @@ import traverse from 'json-schema-traverse';
  *
  * @todo This is a good candidate to be moved into a core `oas` library method.
  * @see {@link https://github.com/mdornseif/json-schema-default}
- * @param jsonSchemas
  */
 export default function getJSONSchemaDefaults(jsonSchemas: SchemaWrapper[]) {
   return jsonSchemas

package/src/core/index.ts

@@ -26,9 +26,9 @@ export interface ConfigOptions {
 
 export interface FetchResponse<status, data> {
   data: data;
-  status: status;
   headers: Headers;
   res: Response;
+  status: status;
 }
 
 // https://stackoverflow.com/a/39495173
@@ -128,7 +128,12 @@ export default class APICore {
           const parsed = await parseResponse(res);
 
           if (res.status >= 400 && res.status <= 599) {
-            throw new FetchError(parsed.status, parsed.data, parsed.headers, parsed.res);
+            throw new FetchError<typeof parsed.status, typeof parsed.data>(
+              parsed.status,
+              parsed.data,
+              parsed.headers,
+              parsed.res
+            );
           }
 
           return parsed;

package/src/core/prepareAuth.ts

@@ -11,8 +11,8 @@ export default function prepareAuth(authKey: (number | string)[], operation: Ope
     | string
     | number
     | {
-        user: string | number;
         pass: string | number;
+        user: string | number;
       }
   > = {};
 

package/src/core/prepareParams.ts

@@ -76,7 +76,7 @@ function merge(src: any, target: any) {
 function processFile(
   paramName: string,
   file: string | ReadStream
-): Promise<{ paramName: string; base64: string; filename: string; buffer: Buffer }> {
+): Promise<{ base64: string; buffer: Buffer; filename: string; paramName: string }> {
   if (typeof file === 'string') {
     // In order to support relative pathed files, we need to attempt to resolve them.
     const resolvedFile = path.resolve(file);

package/src/core/prepareServer.ts

@@ -12,9 +12,6 @@ function stripTrailingSlash(url: string) {
  * With an SDK server config and an instance of OAS we should extract and prepare the server and
  * any server variables to be supplied to `@readme/oas-to-har`.
  *
- * @param spec
- * @param url
- * @param variables
  */
 export default function prepareServer(spec: Oas, url: string, variables: Record<string, string | number> = {}) {
   let serverIdx;

package/src/index.ts

@@ -41,7 +41,6 @@ class Sdk {
      * Create dynamic accessors for every operation with a defined operation ID. If an operation
      * does not have an operation ID it can be accessed by its `.method('/path')` accessor instead.
      *
-     * @param spec
      */
     function loadOperations(spec: Oas) {
       return Object.entries(spec.getPaths())

package/src/packageInfo.ts

@@ -1,3 +1,3 @@
 // This file is automatically updated by the build script.
 export const PACKAGE_NAME = 'api';
-export const PACKAGE_VERSION = '6.0.0';
+export const PACKAGE_VERSION = '6.1.0';