api 5.0.0-beta.2 → 5.0.0

package/README.md

@@ -17,7 +17,7 @@
 - [Usage](https://api.readme.dev/docs/usage)
   - [Authentication](https://api.readme.dev/docs/authentication)
   - [Parameters and Payloads](https://api.readme.dev/docs/parameters-and-payloads)
-  - [HTTP requests](https://api.readme.dev/docs/http-requests)
+  - [Making requests](https://api.readme.dev/docs/making-requests)
   - [Server configurations](https://api.readme.dev/docs/server-configurations)
 - [How does it work?](https://api.readme.dev/docs/how-it-works)
 - [FAQ](https://api.readme.dev/docs/faq)
@@ -29,22 +29,21 @@ $ npx api install https://raw.githubusercontent.com/OAI/OpenAPI-Specification/ma
 ```
 
 ```js
-const SDK = require('@api/petstore');
+const petstore = require('@api/petstore');
 
-const petstore = new SDK();
-petstore.listPets().then(res => {
-  console.log(`My pets name is ${res[0].name}!`);
+petstore.listPets().then(({ data }) => {
+  console.log(`My pets name is ${data[0].name}!`);
 });
 ```
 
-Or you can use it dynamically (though you won't have fancy TypeScript types):
+Or you can use it dynamically (though you won't have fancy TypeScript types to help you out!):
 
 ```js
 const petstore = require('api')(
   'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json'
 );
 
-petstore.listPets().then(res => {
-  console.log(`My pets name is ${res[0].name}!`);
+petstore.listPets().then(({ data })) => {
+  console.log(`My pets name is ${data[0].name}!`);
 });
 ```

package/dist/bin.js

@@ -63,8 +63,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 exports.__esModule = true;
 var commander_1 = require("commander");
-var pkg = __importStar(require("./packageInfo"));
 var commands_1 = __importDefault(require("./cli/commands"));
+var pkg = __importStar(require("./packageInfo"));
 (function () { return __awaiter(void 0, void 0, void 0, function () {
     var program;
     return __generator(this, function (_a) {

package/dist/cache.d.ts

@@ -1,4 +1,4 @@
-import type { OASDocument } from 'oas/@types/rmoas.types';
+import type { OASDocument } from 'oas/dist/rmoas.types';
 import 'isomorphic-fetch';
 import Fetcher from './fetcher';
 declare type CacheStore = Record<string, {
@@ -20,11 +20,46 @@ export default class Cache {
     static getCacheHash(file: string | OASDocument): string;
     static setCacheDir(dir?: string | false): void;
     static reset(): Promise<void>;
-    static validate(json: any): Promise<import("openapi-types").OpenAPI.Document<{}>>;
     isCached(): boolean;
     getCache(): CacheStore;
     get(): any;
-    load(): Promise<OASDocument>;
+    load(): Promise<import("openapi-types").OpenAPIV3.Document<{}> | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "paths"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "paths">) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "webhooks"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "webhooks">) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[];
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "components"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "components">) | import("openapi-types").OpenAPIV2.Document<{}>>;
     save(spec: OASDocument): OASDocument;
 }
 export {};

package/dist/cache.js

@@ -39,16 +39,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 exports.__esModule = true;
-require("isomorphic-fetch");
-var openapi_parser_1 = __importDefault(require("@readme/openapi-parser"));
 var crypto_1 = __importDefault(require("crypto"));
-var find_cache_dir_1 = __importDefault(require("find-cache-dir"));
 var fs_1 = __importDefault(require("fs"));
 var os_1 = __importDefault(require("os"));
 var path_1 = __importDefault(require("path"));
+var find_cache_dir_1 = __importDefault(require("find-cache-dir"));
+require("isomorphic-fetch");
 var make_dir_1 = __importDefault(require("make-dir"));
-var packageInfo_1 = require("./packageInfo");
 var fetcher_1 = __importDefault(require("./fetcher"));
+var packageInfo_1 = require("./packageInfo");
 var Cache = /** @class */ (function () {
     function Cache(uri, cacheDir) {
         if (cacheDir === void 0) { cacheDir = false; }
@@ -120,25 +119,6 @@ var Cache = /** @class */ (function () {
             });
         });
     };
-    Cache.validate = function (json) {
-        if (json.swagger) {
-            throw new Error('Sorry, this module only supports OpenAPI definitions.');
-        }
-        // The `validate` method handles dereferencing for us.
-        return openapi_parser_1["default"].validate(json, {
-            dereference: {
-                // If circular `$refs` are ignored they'll remain in the API definition as `$ref: String`.
-                // This allows us to not only do easy circular reference detection but also stringify and
-                // save dereferenced API definitions back into the cache directory.
-                circular: 'ignore'
-            }
-        })["catch"](function (err) {
-            if (/is not a valid openapi definition/i.test(err.message)) {
-                throw new Error("Sorry, that doesn't look like a valid OpenAPI definition.");
-            }
-            throw err;
-        });
-    };
     Cache.prototype.isCached = function () {
         var cache = this.getCache();
         return cache && this.uriHash in cache;
@@ -178,10 +158,11 @@ var Cache = /** @class */ (function () {
         return __awaiter(this, void 0, void 0, function () {
             var _this = this;
             return __generator(this, function (_a) {
-                // If the class was supplied a raw object, just go ahead and bypass the caching system and
-                // return that.
+                // If the class was supplied a raw object we should still validate and make sure that it's
+                // dereferenced in order for everything to function, but we shouldn't worry about saving it
+                // into the cache directory architecture.
                 if (typeof this.uri === 'object') {
-                    return [2 /*return*/, this.uri];
+                    return [2 /*return*/, fetcher_1["default"].validate(this.uri)];
                 }
                 return [2 /*return*/, this.fetcher.load().then(function (spec) { return __awaiter(_this, void 0, void 0, function () { return __generator(this, function (_a) {
                         return [2 /*return*/, this.save(spec)];

package/dist/cli/codegen/index.d.ts

@@ -1,4 +1,4 @@
-import type Oas from 'oas';
 import type CodeGeneratorLanguage from './language';
+import type Oas from 'oas';
 export declare type SupportedLanguages = 'js' | 'js-cjs' | 'js-esm' | 'ts';
 export default function codegen(language: SupportedLanguages, spec: Oas, specPath: string, identifier: string): CodeGeneratorLanguage;

package/dist/cli/codegen/language.d.ts

@@ -1,5 +1,5 @@
-import type Oas from 'oas';
 import type Storage from '../storage';
+import type Oas from 'oas';
 export interface InstallerOptions {
     /**
      * Will initiate a dry run install process. Used for simulating installations within a unit test.

package/dist/cli/codegen/language.js

@@ -10,6 +10,19 @@ var CodeGeneratorLanguage = /** @class */ (function () {
         // a `petstore` spec installed on api@4.2.0.
         var info = spec.getDefinition().info;
         this.userAgent = "".concat(identifier, "/").concat(info.version, " (").concat(packageInfo_1.PACKAGE_NAME, "/").concat(packageInfo_1.PACKAGE_VERSION, ")");
+        /**
+         * This check is barbaric but there are a number of issues with how the `transformer` work we
+         * have in `oas` and in `.getParametersAsJSONSchema()` and `.getResponseAsJSONSchema()` that
+         * are fully crashing when attempting to codegen an SDK for an API definition that has a
+         * circular reference.
+         *
+         * In order to get v5 out the door we're not going to support this case initialy.
+         *
+         * @see {@link https://github.com/readmeio/api/issues/549}
+         */
+        if (JSON.stringify(spec.api).includes('"$ref":"#/')) {
+            throw new Error('Sorry, this library does not yet support generating an SDK for an OpenAPI definition that contains circular references.');
+        }
     }
     CodeGeneratorLanguage.prototype.hasRequiredPackages = function () {
         return Boolean(Object.keys(this.requiredPackages));

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

@@ -0,0 +1,21 @@
+export declare function formatter(content: string): string;
+/**
+ * @see {@link https://www.30secondsofcode.org/js/s/word-wrap}
+ */
+export declare function wordWrap(str: string, max?: number): string;
+/**
+ * Safely escape some string characters that may break a docblock.
+ *
+ */
+export declare function docblockEscape(str: string): string;
+/**
+ * Convert a string that might contain spaces or special characters to one that can safely be used
+ * as a TypeScript interface or enum name.
+ *
+ * This function has been adapted and slighty modified from `json-schema-to-typescript`.
+ *
+ * @license MIT
+ * @see {@link https://github.com/bcherny/json-schema-to-typescript}
+ */
+export declare function toSafeString(str: string): string;
+export declare function generateTypeName(...parts: string[]): string;

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

@@ -0,0 +1,185 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+exports.__esModule = true;
+exports.generateTypeName = exports.toSafeString = exports.docblockEscape = exports.wordWrap = exports.formatter = void 0;
+var lodash_camelcase_1 = __importDefault(require("lodash.camelcase"));
+var lodash_deburr_1 = __importDefault(require("lodash.deburr"));
+var lodash_startcase_1 = __importDefault(require("lodash.startcase"));
+var prettier_1 = require("prettier");
+/**
+ * This is a mix of reserved JS words and keywords in TypeScript that might be reserved or
+ * allowable but functionally confusing (like `let any = 'buster';`)
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar}
+ */
+var RESERVED_WORDS = [
+    'abstract',
+    'any',
+    'arguments',
+    'as',
+    'async',
+    'await',
+    'boolean',
+    'break',
+    'byte',
+    'case',
+    'catch',
+    'char',
+    'class',
+    'const',
+    'continue',
+    'constructor',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'double',
+    'else',
+    'enum',
+    'eval',
+    'export',
+    'extends',
+    'false',
+    'final',
+    'finally',
+    'float',
+    'for',
+    'from',
+    'function',
+    'get',
+    'goto',
+    'if',
+    'implements',
+    'import',
+    'interface',
+    'in',
+    'instanceof',
+    'int',
+    'let',
+    'long',
+    'native',
+    'new',
+    'null',
+    'number',
+    'of',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'module',
+    'namespace',
+    'return',
+    'set',
+    'short',
+    'static',
+    'string',
+    'super',
+    'switch',
+    'synchronized',
+    'this',
+    'throw',
+    'throws',
+    'transient',
+    'true',
+    'try',
+    'type',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'volatile',
+    'yield',
+    // These aren't reserved keywords but because we maybe codegen'ing an SDK to be used in the
+    // browser it'd be very bad if we overwrote these. This obviously doesn't account for browser APIs
+    // you can access outside of the `Window` API (like `alert()`), but we can add checks for those
+    // later if we need to.
+    'frames',
+    'global',
+    'globalThis',
+    'navigator',
+    'self',
+    'window',
+];
+function formatter(content) {
+    return (0, prettier_1.format)(content, {
+        parser: 'typescript',
+        printWidth: 100,
+        singleQuote: true
+    });
+}
+exports.formatter = formatter;
+/**
+ * @see {@link https://www.30secondsofcode.org/js/s/word-wrap}
+ */
+function wordWrap(str, max) {
+    if (max === void 0) { max = 88; }
+    return str.replace(new RegExp("(?![^\\n]{1,".concat(max, "}$)([^\\n]{1,").concat(max, "})\\s"), 'g'), '$1\n');
+}
+exports.wordWrap = wordWrap;
+/**
+ * Safely escape some string characters that may break a docblock.
+ *
+ */
+function docblockEscape(str) {
+    return str.replace(/\/\*/g, '/\\*').replace(/\*\//g, '*\\/');
+}
+exports.docblockEscape = docblockEscape;
+/**
+ * Convert a string that might contain spaces or special characters to one that can safely be used
+ * as a TypeScript interface or enum name.
+ *
+ * This function has been adapted and slighty modified from `json-schema-to-typescript`.
+ *
+ * @license MIT
+ * @see {@link https://github.com/bcherny/json-schema-to-typescript}
+ */
+function toSafeString(str) {
+    // identifiers in javaScript/ts:
+    // First character: a-zA-Z | _ | $
+    // Rest: a-zA-Z | _ | $ | 0-9
+    // remove accents, umlauts, ... by their basic latin letters
+    return ((0, lodash_deburr_1["default"])(str)
+        // if the string starts with a number, prefix it with character that typescript can accept
+        // https://github.com/bcherny/json-schema-to-typescript/issues/489
+        .replace(/^(\d){1}/, '$$1')
+        // replace chars which are not valid for typescript identifiers with whitespace
+        .replace(/(^\s*[^a-zA-Z_$])|([^a-zA-Z_$\d])/g, ' ')
+        // uppercase leading underscores followed by lowercase
+        .replace(/^_[a-z]/g, function (match) { return match.toUpperCase(); })
+        // remove non-leading underscores followed by lowercase (convert snake_case)
+        .replace(/_[a-z]/g, function (match) { return match.substr(1, match.length).toUpperCase(); })
+        // uppercase letters after digits, dollars
+        .replace(/([\d$]+[a-zA-Z])/g, function (match) { return match.toUpperCase(); })
+        // uppercase first letter after whitespace
+        .replace(/\s+([a-zA-Z])/g, function (match) { return match.toUpperCase().trim(); })
+        // remove remaining whitespace
+        .replace(/\s/g, ''));
+}
+exports.toSafeString = toSafeString;
+function generateTypeName() {
+    var parts = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        parts[_i] = arguments[_i];
+    }
+    var str;
+    // If the end of our string ends with something like `2XX`, the combination of `startCase` and
+    // `camelCase` will transform it into `2Xx`.
+    if (parts.length > 1) {
+        var last = parts[parts.length - 1];
+        if (last.match(/^(\d)XX$/)) {
+            str = (0, lodash_startcase_1["default"])((0, lodash_camelcase_1["default"])(parts.slice(0, -1).join(' ')));
+            str += " ".concat(last);
+        }
+    }
+    if (!str) {
+        str = (0, lodash_startcase_1["default"])((0, lodash_camelcase_1["default"])(parts.join(' ')));
+    }
+    if (RESERVED_WORDS.includes(str.toLowerCase())) {
+        str = "$".concat(str);
+    }
+    return toSafeString(str);
+}
+exports.generateTypeName = generateTypeName;

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

@@ -1,11 +1,14 @@
-import type Oas from 'oas';
-import type { Operation } from 'oas';
-import type { JSONSchema, SchemaObject } from 'oas/@types/rmoas.types';
-import type { ClassDeclaration, MethodDeclaration } from 'ts-morph';
 import type Storage from '../../storage';
 import type { InstallerOptions } from '../language';
-import CodeGeneratorLanguage from '../language';
+import type Oas from 'oas';
+import type { Operation } from 'oas';
+import type { ClassDeclaration } from 'ts-morph';
 import { Project } from 'ts-morph';
+import CodeGeneratorLanguage from '../language';
+export declare type TSGeneratorOptions = {
+    outputJS?: boolean;
+    compilerTarget?: 'cjs' | 'esm';
+};
 declare type OperationTypeHousing = {
     types: {
         params?: false | Record<'body' | 'formData' | 'metadata', string>;
@@ -19,18 +22,14 @@ export default class TSGenerator extends CodeGeneratorLanguage {
     compilerTarget: 'cjs' | 'esm';
     types: Map<string, string>;
     files: Record<string, string>;
-    methodGenerics: Map<string, MethodDeclaration>;
     sdk: ClassDeclaration;
-    schemas: Map<string, {
-        schema: SchemaObject;
-        name: string;
-        tsType?: string;
-    }>;
-    constructor(spec: Oas, specPath: string, identifier: string, opts?: {
-        outputJS?: boolean;
-        compilerTarget?: 'cjs' | 'esm';
-    });
-    static formatter(content: string): string;
+    schemas: Record<string, {
+        body?: any;
+        metadata?: any;
+        response?: Record<string, any>;
+    } | Record<string, any>>;
+    usesHTTPMethodRangeInterface: boolean;
+    constructor(spec: Oas, specPath: string, identifier: string, opts?: TSGeneratorOptions);
     installer(storage: Storage, opts?: InstallerOptions): Promise<void>;
     /**
      * Compile the current OpenAPI definition into a TypeScript library.
@@ -40,60 +39,56 @@ export default class TSGenerator extends CodeGeneratorLanguage {
         [x: string]: string;
     }>;
     /**
-     * Create a generic HTTP method accessor on the SDK.
+     * Create our main SDK source file.
      *
-     * @param method
      */
-    createGenericMethodAccessor(method: string): void;
+    createSourceFile(): import("ts-morph").SourceFile;
     /**
-     * Create operation accessors on the SDK.
+     * Create our main schemas file. This is where all of the JSON Schema that our TypeScript typing
+     * infrastructure sources its data from. Without this there are no types.
      *
-     * @param operation
-     * @param operationId
-     * @param paramTypes
-     * @param responseTypes
      */
-    createOperationAccessor(operation: Operation, operationId: string, paramTypes?: OperationTypeHousing['types']['params'], responseTypes?: OperationTypeHousing['types']['responses']): void;
+    createSchemasFile(): import("ts-morph").SourceFile;
     /**
-     * Convert a JSON Schema object into a readily available TypeScript type or interface along with
-     * any `$ref` pointers that are in use and turn those into TS types too.
+     * Create our main types file. This sources its data from the JSON Schema `schemas.ts` file and
+     * will re-export types to be used in TypeScript implementations and IDE intellisense. This
+     * typing work is functional with the `json-schema-to-ts` library.
      *
-     * Under the hood this uses https://npm.im/json-schema-to-typescript for all composition and
-     * conversion.
+     * @see {@link https://npm.im/json-schema-to-ts}
+     */
+    createTypesFile(): import("ts-morph").SourceFile;
+    /**
+     * Create operation accessors on the SDK.
      *
-     * @param schema
-     * @param name
      */
-    convertJSONSchemaToTypescript(schema: JSONSchema, name: string): Promise<{
-        primaryType: string;
-    }>;
+    createOperationAccessor(operation: Operation, operationId: string, paramTypes?: OperationTypeHousing['types']['params'], responseTypes?: OperationTypeHousing['types']['responses']): void;
     /**
      * Scour through the current OpenAPI definition and compile a store of every operation, along
      * with every HTTP method that's in use, and their available TypeScript types that we can use,
      * along with every HTTP method that's in use.
      *
      */
-    loadOperationsAndMethods(): Promise<{
+    loadOperationsAndMethods(): {
         operations: Record<string, OperationTypeHousing>;
         methods: Set<unknown>;
-    }>;
+    };
     /**
      * Compile the parameter (path, query, cookie, and header) schemas for an API operation into
      * usable TypeScript types.
      *
-     * @param operation
-     * @param operationId
      */
     prepareParameterTypesForOperation(operation: Operation, operationId: string): false | Record<"formData" | "body" | "metadata", string>;
     /**
      * Compile the response schemas for an API operation into usable TypeScript types.
      *
-     * @todo what does this do for a spec that has no responses?
-     * @param operation
-     * @param operationId
      */
     prepareResponseTypesForOperation(operation: Operation, operationId: string): {
         [x: string]: string;
     };
+    /**
+     * Add a given schema into our schema dataset that we'll be be exporting as types.
+     *
+     */
+    addSchemaToExport(schema: any, typeName: string, pointer: string): void;
 }
 export {};