api 5.0.0-beta.0 → 5.0.0-beta.3

package/README.md

@@ -1,179 +1,49 @@
-# 🚀 api
+<p align="center">
+  <img width="400" src="https://raw.githubusercontent.com/readmeio/api/main/docs/images/logo.svg" />
+</p>
 
-[![npm](https://img.shields.io/npm/v/api)](https://npm.im/api) [![Build](https://github.com/readmeio/api/workflows/CI/badge.svg)](https://github.com/readmeio/api)
+<p align="center">
+  Magical SDK generation from an OpenAPI definition 🪄
+</p>
 
-Automatic SDK generation from an OpenAPI definition.
+<p align="center">
+  <a href="https://npm.im/api"><img src="https://img.shields.io/npm/v/api.svg?style=for-the-badge" alt="NPM Version"></a>
+  <a href="https://npm.im/api"><img src="https://img.shields.io/node/v/api.svg?style=for-the-badge" alt="Node Version"></a>
+  <a href="https://npm.im/api"><img src="https://img.shields.io/npm/l/api.svg?style=for-the-badge" alt="MIT License"></a>
+  <a href="https://github.com/readmeio/api"><img src="https://img.shields.io/github/workflow/status/readmeio/api/CI.svg?style=for-the-badge" alt="Build status"></a>
+</p>
 
-* [Installation](#installation)
-* [Usage](#usage)
-    * [Authentication](#authentication)
-    * [Parameters and Payloads](#parameters-and-payloads)
-    * [HTTP requests](#http-requests)
-    * [Server configurations](#server-configurations)
-* [How does it work?](#how-does-it-work)
-* [Interested in contributing?](#interested-in-contributing)
-* [FAQ](#faq)
+- [Installation](https://api.readme.dev/docs/installation)
+- [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)
+  - [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)
 
-## Installation
-```
-npm install api --save
-```
-
-## Usage
-All you need to use `api` is to supply it an OpenAPI definition and then use the SDK as you would any other!
-
-```js
-const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json');
-
-sdk.listPets().then(res => {
-  console.log(`My pets name is ${res[0].name}!`);
-});
-```
-
-The OpenAPI definition is automatically downloaded, cached, and transformed into a chainable [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) Promise that you can use to make API requests.
-
-### Authentication
-`api` supports API authentication through an `.auth()` method:
-
-```js
-sdk.auth('myApiToken');
-sdk.listPets().then(...);
-```
-
-With the exception of OpenID, it supports all forms of authentication supported by the OpenAPI specification! Supply `.auth()` with your auth credentials and it'll magically figure out how to use it according to the API you're using. 🧙‍♀️
-
-For example:
-
-* HTTP Basic auth: `sdk.auth('username', 'password')`
-* Bearer tokens (HTTP or OAuth 2): `sdk.auth('myBearerToken')`
-* API Keys: `sdk.auth('myApiKey')`
-
-> ℹ️ Note that `sdk.auth()` is not chainable.
+`api` is a library that facilitates creating an SDK from an OpenAPI definition. You can use its codegen offering to create an opinionated SDK for TypeScript or JS (+ TypeScript types).
 
-### Parameters and Payloads
-When supplying parameters and/or request body payloads to an API request, you don't need to explicitly define what goes where since the API definition contains all that information. All you need to do is supply either one or two objects:
-
-* `body`: This will contain all data required for a request body payload for a POST, PUT, etc. request. It can either be an array or an object — whichever you need to use the API operation you're using.
-* `metadata`: This is an object where all parameters (path, query, header, cookie) go. Again, don't worry about telling the SDK that a path parameter is for the path, that's all handled for you.
-
-For example, if you wanted to make a GET request:
-
-```js
-sdk.showPetById({ petId: 1234 }).then(...)
-```
-
-Since `petId` matches up with the `petId` path parameter, the SDK here will issue a GET request against `/pets/1234`.
-
-What about a POST request?
-
-```js
-sdk.createPets({ name: 'Buster' }).then(...)
+```sh
+$ npx api install https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json
 ```
 
-Since `name` here would correspond on `createPets` to request body payload, this will issue a POST request against `/pets` to make a new pet named "Buster".
-
-What about operations that require both? Well you can mix them too!
-
 ```js
-sdk.updatePet({ name: 'Buster 2' }, { petId: 1234 }).then(...)
-```
-
-Since we've supplied two objects here, the SDK automatically knows that you're supplying both a `body` and `metadata`, and can make a PUT request against `/pets/1234` for you.
-
-What about a `multipart/form-data` request? That works too, and you don't even have to worry about the fun of multipart boundaries!
-
-```js
-sdk.uploadFile({ file: '/path/to/a/file.txt' }).then(...)
-```
-
-You can also give it a stream and it'll handle all of the hard work for you.
+const SDK = require('@api/petstore');
 
-```js
-sdk.uploadFile({ file: fs.createReadStream('/path/to/a/file.txt') }).then(...)
-```
-
-### HTTP requests
-If the API you're using doesn't have any documented operation IDs, you can make requests with HTTP verbs instead:
-
-```js
-sdk.get('/pets/{petId}', { petId: 1234 }).then(...)
-```
-
-The SDK supports GET, PUT, POST, DELETE, OPTIONS, HEAD, and TRACE requests.
-
-### Server configurations
-If the API you're using offers alternate server URLs and server variables in its [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#serverObject) definition you can supply this to the SDK with `.server()`:
-
-```js
-sdk.server('https://{region}.api.example.com/{basePath}', {
-  name: 'eu',
-  basePath: 'v14',
+petstore.listPets().then(res => {
+  console.log(`My pets name is ${res[0].name}!`);
 });
-
-sdk.get('/pets').then(...)
 ```
 
-When your request is executed it will be made to `https://eu.api.example.com/v14/pets`. Alternatively if you don't want to deal with URL templates you can opt to pass the full URL in instead:
+Or you can use it dynamically (though you won't have fancy TypeScript types):
 
 ```js
-sdk.server('https://eu.api.example.com/v14');
-```
-
-## How does it work?
-Behind the scenes, `api` will:
-
-1. Download the supplied OpenAPI definition, either from a publically accessible URLs or an absolute/relative path.
-2. Dereference the definition so it's easier for us to handle.
-3. Hash the definition and cache it into a directory in `node_modules/.cache/api/`.
-4. Process the definition and instantiate chainable methods for HTTP verbs and operation IDs the API contains via a JS [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy).
-
-On subsequent requests, `api` will look in its cache, and if the supplied definition exists there, it'll retrieve it from the cache instead of re-retrieving it again.
-
-## Interested in contributing?
-Welcome! Have a look at [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## FAQ
-#### Does this support YAML definitions?
-Yes! YAML definitions will be automatically converted to JSON before they're cached and loaded as an SDK.
+const petstore = require('api')(
+  'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json'
+);
 
-#### Does this support Swagger 2.0 definitions?
-At the moment it does not. If you wish to use an API that has a Swagger 2.0 file, you'll need to first convert it to an OpenAPI 3 definition.
-
-#### Does this support traditional OAuth 2 flows of creating tokens?
-Not yet, unfortunately. For APIs that use OAuth 2, you'll need a fully-qualified token already for `api` to make requests.
-
-#### Does this support APIs that use multiple forms of authentication on a single request?
-Not yet! This is something we're thinking about how to handle, but it's difficult with the simplified nature of the `.auth()` method as it currently does not require the user to inform the SDK of what kind of authentication scheme the token they're supplying it should match up against.
-
-#### Will this work in browsers?
-Not at the moment as the library requires some filesystem handling in order to manage its cache state, but it's something we're actively thinking about. If you'd like to help us out in making this compatible with browsers we'd love to help you out on a pull request.
-
-#### Will this validate my data before it reaches the API?
-Not yet! This is something we've got planned down the road.
-
-#### Does this support OpenAPI definitions that require authentication to download?
-Not yet! The URL that you give the module must be publicy accessible. If it isn't, you can download it to your computer/server and then use the absolute path to that file instead.
-
-```js
-const sdk = require('api')('/path/to/downloaded.json');
-```
-
-#### How do I access the Response object (for status and headers)?
-By default we parse the response based on the `content-type` header for you. You can disable this by doing the following:
-
-```js
-sdk.config({ parseResponse: false });
-```
-
-#### Where is the cache stored?
-
-By default the cache is configured with the [find-cache-dir](https://npm.im/find-cache-dir) library so the cache will be in `node_modules/.cache/api`. If placing this cache within the `node_modules/` directory is a problem for your environment (maybe you use `npm prune`) you can configure this by supplying an additional argument to the SDK instantiator:
-
-```js
-const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json', {
-  cacheDir: './path/to/my/custom/cache/dir',
-});
-sdk.listPets().then(res => {
+petstore.listPets().then(res => {
   console.log(`My pets name is ${res[0].name}!`);
 });
 ```

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, {

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

@@ -1,11 +1,15 @@
 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 { JSONSchema, SchemaObject } from 'oas/dist/rmoas.types';
+import type { ClassDeclaration, MethodDeclaration, VariableStatement } from 'ts-morph';
 import type Storage from '../../storage';
 import type { InstallerOptions } from '../language';
 import CodeGeneratorLanguage from '../language';
 import { Project } from 'ts-morph';
+export declare type TSGeneratorOptions = {
+    outputJS?: boolean;
+    compilerTarget?: 'cjs' | 'esm';
+};
 declare type OperationTypeHousing = {
     types: {
         params?: false | Record<'body' | 'formData' | 'metadata', string>;
@@ -21,15 +25,13 @@ export default class TSGenerator extends CodeGeneratorLanguage {
     files: Record<string, string>;
     methodGenerics: Map<string, MethodDeclaration>;
     sdk: ClassDeclaration;
+    sdkExport: VariableStatement;
     schemas: Map<string, {
         schema: SchemaObject;
         name: string;
         tsType?: string;
     }>;
-    constructor(spec: Oas, specPath: string, identifier: string, opts?: {
-        outputJS?: boolean;
-        compilerTarget?: 'cjs' | 'esm';
-    });
+    constructor(spec: Oas, specPath: string, identifier: string, opts?: TSGeneratorOptions);
     static formatter(content: string): string;
     installer(storage: Storage, opts?: InstallerOptions): Promise<void>;
     /**

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

@@ -114,7 +114,7 @@ var TSGenerator = /** @class */ (function (_super) {
                 indentationText: ts_morph_1.IndentationText.TwoSpaces,
                 quoteKind: ts_morph_1.QuoteKind.Single
             },
-            compilerOptions: __assign({ declaration: true, resolveJsonModule: true, target: options.compilerTarget === 'cjs' ? ts_morph_1.ScriptTarget.ES5 : ts_morph_1.ScriptTarget.ES2020, outDir: 'dist' }, (options.compilerTarget === 'cjs' ? { esModuleInterop: true } : {}))
+            compilerOptions: __assign({ declaration: true, outDir: 'dist', resolveJsonModule: true, target: options.compilerTarget === 'cjs' ? ts_morph_1.ScriptTarget.ES5 : ts_morph_1.ScriptTarget.ES2020 }, (options.compilerTarget === 'cjs' ? { esModuleInterop: true } : {}))
         });
         _this.compilerTarget = options.compilerTarget;
         _this.outputJS = options.outputJS;
@@ -195,24 +195,57 @@ var TSGenerator = /** @class */ (function (_super) {
                         this.sdk = sdkSource.addClass({
                             name: 'SDK'
                         });
-                        // There's an annoying quirk with `ts-morph` where if we set the SDK class to be the default
-                        // export with `isDefaultExport` then when we compile it to an ES5 target for CJS environments
-                        // it'll be exported as `export.default = SDK`, which when you try to load it you'll need to
-                        // run `require('@api/sdk').default`.
-                        //
-                        // Instead here by plainly creating the SDK class in the source file and then setting this
-                        // export assignment it'll export the SDK class as `module.exports = SDK` so people can cleanly
-                        // load the SDK with `require('@api/sdk)`.
-                        //
-                        // A whole lot of debugging went into here to let people not have to worry about `.default`
-                        // messes. I hope it's worth it!
+                        this.sdkExport = sdkSource.addVariableStatement({
+                            declarationKind: ts_morph_1.VariableDeclarationKind.Const,
+                            declarations: [
+                                {
+                                    name: 'createSDK',
+                                    initializer: function (writer) {
+                                        // `ts-morph` doesn't have any way to cleanly create an IFEE.
+                                        writer.writeLine('(() => { return new SDK(); })()');
+                                        return writer;
+                                    }
+                                },
+                            ]
+                        });
+                        /**
+                         * There's an annoying quirk with `ts-morph` where if we set the `createSDK` function to be the
+                         * default export with `isDefaultExport` then when we compile it to an ES5 target for CJS
+                         * environments it'll be exported as `export.default = createSDK`, which when you try to load it
+                         * you'll need to run `require('@api/sdk').default`.
+                         *
+                         * Instead here by plainly creating `createSDK` in the source file and then setting this export
+                         * assignment it'll export the SDK IFEE initializer as `module.exports = createSDK` so people
+                         * can cleanly load their SDK with `require('@api/sdk)`.
+                         *
+                         * A whole lot of debugging went into here to let people not have to worry about `.default`
+                         * messes. I hope it's worth it!
+                         */
                         if (this.compilerTarget === 'cjs') {
                             sdkSource.addExportAssignment({
-                                expression: 'SDK'
+                                expression: 'createSDK'
                             });
                         }
                         else {
-                            this.sdk.setIsDefaultExport(true);
+                            /**
+                             * Because `createSDK` above is an IFEE constant we can't use `setIsDefaultExport` on it due
+                             * to `ts-morph` not having great handling for IFEE's.
+                             *
+                             * If we were to call `setIsDefaultExport` on our IFEE to attempt to compile it as
+                             * `export default createSDK` then `ts-morph` hard crashes with a "Error replacing tree: The
+                             * children of the old and new trees were expected to have the same count" exception due to
+                             * it not being able properly handle IFEE's. It's for that reason that we need to manually
+                             * write a statement expression to set `createSDK` as the default export.
+                             *
+                             * Another quirk that this work avoids is there being an empty `export {};` at the very end
+                             * of our compiled `d.ts` declaration file. I'm not sure why it was being added, and it
+                             * didn't appear to be harming anything, but us manually creating this export statement
+                             * causes it to go away.
+                             *
+                             * Thankfully, fortunately, and curiously, these are all only problems in non-CJS compiled
+                             * targets. ¯\_(ツ)_/¯
+                             */
+                            sdkSource.addStatements('export default createSDK');
                         }
                         this.sdk.addProperties([
                             { name: 'spec', type: 'Oas' },
@@ -313,7 +346,42 @@ var TSGenerator = /** @class */ (function (_super) {
                         // @todo should all of these isolated into their own file outside of the main sdk class file?
                         // Add all known types that we're using into the SDK.
                         Array.from(this.types.values()).forEach(function (exp) {
-                            sdkSource.addStatements(exp);
+                            /**
+                             * When `ts-morph` compiles declaration files when we're targeting CJS environments it creates
+                             * the default export as `export = _default` instead of `export default const _default`. This
+                             * causes TS to throw a TS2309 error for "An export assignment cannot be used in a module
+                             * with other exported elements" because our types and interfaces are also being exported and
+                             * the `export =` overrides those.
+                             *
+                             * Fixing this is, to be frank, a fucking HARD problem for a couple reasons:
+                             *
+                             *  1. Our JSON Schema types and interfaces are coming from `json-schema-to-typescript` and
+                             *    that library exports its data a raw string containing multiple types and interfaces.
+                             *    The only way we're able to capture and use them in our codegenerated SDK is because
+                             *    we're ingesting that string into `ts-morph` and then using its APIs to extract exported
+                             *    declarations (which are still strings) and then they're re-inserted into our main
+                             *    source file here.
+                             *  2. Though `ts-morph` has APIs for adding type aliases and interfaces to a source file what
+                             *    it doesn't have is the ability to pass in a string, or a `Writer` class that exposes,
+                             *    to write raw strings to a type or an interface. If it did we'd be able to replace this
+                             *    `addStatements` call with an `addTypeAlias` and `addInterface` call for each of our
+                             *    JSON Schema schemas that we've got along with an `isExported` flag for `ts-morph` to
+                             *    export it.
+                             *
+                             * Because neither of these are solvable problems right now we're instead opting to **not**
+                             * export types and interfaces from these SDKs. This isn't a great solution because it
+                             * /slightly/ reduces the usability of the TS codegen functionality but in order for the TS
+                             * declaration files that we generate to be valid this is the only option that we've got.
+                             *
+                             * However, that said, if somebody needs an interface or type exported they can export it
+                             * themselves in the SDK code that we compile for them.
+                             *
+                             * @fixme
+                             */
+                            sdkSource.addStatements(
+                            // All expressions coming out of `json-schema-to-typescript` are exported so by popping this
+                            // off we'll just be inserting plain interfaces and types into the SDK source.
+                            exp.substring('export '.length));
                         });
                         if (this.outputJS) {
                             return [2 /*return*/, this.project
@@ -354,7 +422,7 @@ var TSGenerator = /** @class */ (function (_super) {
         var parameters = [{ name: 'path', type: 'string' }];
         var docblock = {
             description: function (writer) {
-                writer.writeLine("Access any ".concat(method, " endpoint on your API."));
+                writer.writeLine("Access any ".concat(method.toUpperCase(), " endpoint on your API."));
                 return writer;
             },
             tags: [{ tagName: 'param', text: 'path API path to make a request against.' }]
@@ -540,7 +608,7 @@ var TSGenerator = /** @class */ (function (_super) {
                 this.methodGenerics.get(operation.method).addOverload({
                     typeParameters: typeParameters,
                     parameters: [
-                        { name: 'path', type: 'string' },
+                        { name: 'path', type: "'".concat(operation.path, "'") },
                         __assign(__assign({}, parameters.body), { hasQuestionToken: false }),
                         __assign(__assign({}, parameters.metadata), { hasQuestionToken: false }),
                     ],
@@ -550,7 +618,7 @@ var TSGenerator = /** @class */ (function (_super) {
                 // Create an overload that just has a single `metadata` parameter.
                 this.methodGenerics.get(operation.method).addOverload({
                     typeParameters: typeParameters,
-                    parameters: [{ name: 'path', type: 'string' }, parameters.metadata],
+                    parameters: [{ name: 'path', type: "'".concat(operation.path, "'") }, parameters.metadata],
                     returnType: returnType,
                     docs: docblock ? [docblock] : null
                 });
@@ -558,7 +626,7 @@ var TSGenerator = /** @class */ (function (_super) {
             else {
                 this.methodGenerics.get(operation.method).addOverload({
                     typeParameters: responseTypes ? null : ['T = unknown'],
-                    parameters: __spreadArray([{ name: 'path', type: 'string' }], Object.values(parameters), true),
+                    parameters: __spreadArray([{ name: 'path', type: "'".concat(operation.path, "'") }], Object.values(parameters), true),
                     returnType: returnType,
                     docs: docblock ? [docblock] : null
                 });
@@ -629,11 +697,15 @@ var TSGenerator = /** @class */ (function (_super) {
                             Object.entries(ops).forEach(function (_a) {
                                 var method = _a[0], operation = _a[1];
                                 methods.add(method);
-                                var operationId = operation.getOperationId();
+                                var operationId = operation.getOperationId({
+                                    // This `camelCase` option will clean up any weird characters that might be present in
+                                    // the `operationId` so as we don't break TS compilation with an invalid method accessor.
+                                    camelCase: true
+                                });
                                 var params = _this.prepareParameterTypesForOperation(operation, operationId);
                                 var responses = _this.prepareResponseTypesForOperation(operation, operationId);
                                 if (operation.hasOperationId()) {
-                                    operations[operation.getOperationId()] = {
+                                    operations[operationId] = {
                                         types: {
                                             params: params,
                                             responses: responses
@@ -722,8 +794,11 @@ var TSGenerator = /** @class */ (function (_super) {
      */
     TSGenerator.prototype.prepareResponseTypesForOperation = function (operation, operationId) {
         var _this = this;
-        var schemas = operation
-            .getResponseStatusCodes()
+        var responseStatusCodes = operation.getResponseStatusCodes();
+        if (!responseStatusCodes.length) {
+            return undefined;
+        }
+        var schemas = responseStatusCodes
             .map(function (status) {
             var _a;
             var schema = operation.getResponseAsJsonSchema(status);

package/dist/cli/storage.d.ts

@@ -1,4 +1,4 @@
-import type { OASDocument } from 'oas/@types/rmoas.types';
+import type { OASDocument } from 'oas/dist/rmoas.types';
 import Fetcher from '../fetcher';
 export default class Storage {
     static dir: string;

package/dist/core/getJSONSchemaDefaults.d.ts

@@ -1,4 +1,4 @@
-import type { SchemaWrapper } from 'oas/@types/operation/get-parameters-as-json-schema';
+import type { SchemaWrapper } from 'oas/dist/operation/get-parameters-as-json-schema';
 /**
  * Run through a JSON Schema object and compose up an object containing default data for any schema
  * property that is required and also has a defined default.

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
 import type Oas from 'oas';
 import type { Operation } from 'oas';
-import type { HttpMethods } from 'oas/@types/rmoas.types';
+import type { HttpMethods } from 'oas/dist/rmoas.types';
 import 'isomorphic-fetch';
 import getJSONSchemaDefaults from './getJSONSchemaDefaults';
 import parseResponse from './parseResponse';

package/dist/core/prepareParams.js

@@ -46,6 +46,8 @@ var stream_1 = __importDefault(require("stream"));
 var get_stream_1 = __importDefault(require("get-stream"));
 var sync_1 = __importDefault(require("datauri/sync"));
 var parser_1 = __importDefault(require("datauri/parser"));
+var remove_undefined_objects_1 = __importDefault(require("remove-undefined-objects"));
+var caseless_1 = __importDefault(require("caseless"));
 var getJSONSchemaDefaults_1 = __importDefault(require("./getJSONSchemaDefaults"));
 /**
  * Extract all available parameters from an operations Parameter Object into a digestable array
@@ -142,7 +144,7 @@ function processFile(paramName, file) {
     }
     return Promise.reject(new TypeError(paramName
         ? "The data supplied for the `".concat(paramName, "` request body parameter is not a file handler that we support.")
-        : "The data supplied for the request body payload is not a file handler that we support."));
+        : 'The data supplied for the request body payload is not a file handler that we support.'));
 }
 /**
  * With potentially supplied body and/or metadata we need to run through them against a given API
@@ -156,7 +158,7 @@ function processFile(paramName, file) {
 function prepareParams(operation, body, metadata) {
     var _a, _b, _c, _d;
     return __awaiter(this, void 0, void 0, function () {
-        var metadataIntersected, digestedParameters, hasDigestedParams, jsonSchema, jsonSchemaDefaults, params, intersection, payloadJsonSchema, conversions_1;
+        var metadataIntersected, digestedParameters, hasDigestedParams, jsonSchema, jsonSchemaDefaults, params, headerParams_1, intersection, payloadJsonSchema, conversions_1;
         return __generator(this, function (_e) {
             switch (_e.label) {
                 case 0:
@@ -164,6 +166,17 @@ function prepareParams(operation, body, metadata) {
                     digestedParameters = digestParameters(operation.getParameters());
                     hasDigestedParams = !!Object.keys(digestedParameters).length;
                     jsonSchema = operation.getParametersAsJsonSchema();
+                    /**
+                     * It might be common for somebody to run `sdk.findPetsByStatus({ status: 'available' }, {})`, in
+                     * which case we want to filter out the second (metadata) parameter and treat the first parameter
+                     * as the metadata instead. If we don't do this, their supplied `status` metadata will be treated
+                     * as a body parameter, and because there's no `status` body parameter, and no supplied metadata
+                     * (because it's an empty object), the request won't send a payload.
+                     *
+                     * @see {@link https://github.com/readmeio/api/issues/449}
+                     */
+                    // eslint-disable-next-line no-param-reassign
+                    metadata = (0, remove_undefined_objects_1["default"])(metadata);
                     if (!jsonSchema && (body !== undefined || metadata !== undefined)) {
                         throw new Error("You supplied metadata and/or body data for this operation but it doesn't have any documented parameters or request payloads. If you think this is an error please contact support for the API you're using.");
                     }
@@ -190,7 +203,24 @@ function prepareParams(operation, body, metadata) {
                                 params.body = merge(params.body, body);
                             }
                             else {
-                                intersection = Object.keys(body).filter(function (value) { return Object.keys(digestedParameters).includes(value); }).length;
+                                headerParams_1 = (0, caseless_1["default"])({});
+                                Object.entries(digestedParameters).forEach(function (_a) {
+                                    var paramName = _a[0], param = _a[1];
+                                    // Headers are sent case-insensitive so we need to make sure that we're properly
+                                    // matching them when detecting what our incoming payload looks like.
+                                    if (param["in"] === 'header') {
+                                        headerParams_1.set(paramName, '');
+                                    }
+                                });
+                                intersection = Object.keys(body).filter(function (value) {
+                                    if (Object.keys(digestedParameters).includes(value)) {
+                                        return true;
+                                    }
+                                    else if (headerParams_1.has(value)) {
+                                        return true;
+                                    }
+                                    return false;
+                                }).length;
                                 if (intersection && intersection / Object.keys(body).length > 0.25) {
                                     /* eslint-disable no-param-reassign */
                                     // If more than 25% of the body intersects with the parameters that we've got on hand,
@@ -290,8 +320,15 @@ function prepareParams(operation, body, metadata) {
                         Object.entries(digestedParameters).forEach(function (_a) {
                             var paramName = _a[0], param = _a[1];
                             var value;
-                            if (typeof metadata === 'object' && !isEmpty(metadata) && paramName in metadata) {
-                                value = metadata[paramName];
+                            if (typeof metadata === 'object' && !isEmpty(metadata)) {
+                                if (paramName in metadata) {
+                                    value = metadata[paramName];
+                                }
+                                else if (param["in"] === 'header') {
+                                    // Headers are sent case-insensitive so we need to make sure that we're properly
+                                    // matching them when detecting what our incoming payload looks like.
+                                    value = metadata[Object.keys(metadata).find(function (k) { return k.toLowerCase() === paramName.toLowerCase(); })];
+                                }
                             }
                             if (value === undefined) {
                                 return;
@@ -307,7 +344,7 @@ function prepareParams(operation, body, metadata) {
                                     delete metadata[paramName];
                                     break;
                                 case 'header':
-                                    params.header[paramName] = value;
+                                    params.header[paramName.toLowerCase()] = value;
                                     delete metadata[paramName];
                                     break;
                                 case 'cookie':

package/dist/fetcher.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';
 export default class Fetcher {
     uri: string | OASDocument;
@@ -9,6 +9,7 @@ export default class Fetcher {
     static registryUUIDRegex: RegExp;
     constructor(uri: string | OASDocument);
     static isAPIRegistryUUID(uri: string): boolean;
+    static isGitHubBlobURL(uri: string): boolean;
     static getProjectPrefixFromRegistryUUID(uri: string): string;
     load(): Promise<(Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
         info: import("openapi-types").OpenAPIV3_1.InfoObject;

package/dist/fetcher.js

@@ -47,10 +47,23 @@ var path_1 = __importDefault(require("path"));
 var Fetcher = /** @class */ (function () {
     function Fetcher(uri) {
         if (typeof uri === 'string') {
-            // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
-            this.uri = Fetcher.isAPIRegistryUUID(uri)
-                ? uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4')
-                : uri;
+            if (Fetcher.isAPIRegistryUUID(uri)) {
+                // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
+                this.uri = uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4');
+            }
+            else if (Fetcher.isGitHubBlobURL(uri)) {
+                /**
+                 * People may try to use a public repository URL to the source viewer on GitHub not knowing
+                 * that this page actually serves HTML. In this case we want to rewrite these to the "raw"
+                 * version of this page that'll allow us to access the API definition.
+                 *
+                 * @example https://github.com/readmeio/oas-examples/blob/main/3.1/json/petstore.json
+                 */
+                this.uri = uri.replace(/\/\/github.com/, '//raw.githubusercontent.com').replace(/\/blob\//, '/');
+            }
+            else {
+                this.uri = uri;
+            }
         }
         else {
             this.uri = uri;
@@ -59,6 +72,9 @@ var Fetcher = /** @class */ (function () {
     Fetcher.isAPIRegistryUUID = function (uri) {
         return Fetcher.registryUUIDRegex.test(uri);
     };
+    Fetcher.isGitHubBlobURL = function (uri) {
+        return /\/\/github.com\/[-_a-zA-Z0-9]+\/[-_a-zA-Z0-9]+\/blob\/(.*).(yaml|json|yml)/.test(uri);
+    };
     Fetcher.getProjectPrefixFromRegistryUUID = function (uri) {
         var matches = uri.match(Fetcher.registryUUIDRegex);
         if (!matches) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { OASDocument } from 'oas/@types/rmoas.types';
+import type { OASDocument } from 'oas/dist/rmoas.types';
 interface SDKOptions {
     cacheDir?: string;
 }

package/dist/packageInfo.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "api";
-export declare const PACKAGE_VERSION = "5.0.0-beta.0";
+export declare const PACKAGE_VERSION = "5.0.0-beta.3";

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 = '5.0.0-beta.0';
+exports.PACKAGE_VERSION = '5.0.0-beta.3';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "api",
-  "version": "5.0.0-beta.0",
-  "description": "Generate an SDK from an OpenAPI definition",
+  "version": "5.0.0-beta.3",
+  "description": "Magical SDK generation from an OpenAPI definition 🪄",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
@@ -10,12 +10,9 @@
   "scripts": {
     "build": "tsc",
     "debug:bin": "node -r ts-node/register src/bin.ts",
-    "lint": "eslint . --ext .js,.ts",
     "prebuild": "rm -rf dist/; npm run prebuild.packageConfig",
-    "prebuild.packageConfig": "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",
+    "prebuild.packageConfig": "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",
     "prepack": "npm run build",
-    "pretest": "npm run lint",
-    "prettier": "prettier --list-different --write \"./**/**.{js,ts}\"",
     "test": "nyc mocha \"test/**/*.test.ts\""
   },
   "repository": {
@@ -23,7 +20,7 @@
     "url": "https://github.com/readmeio/api.git",
     "directory": "packages/api"
   },
-  "homepage": "https://github.com/readmeio/api",
+  "homepage": "https://api.readme.dev",
   "bugs": {
     "url": "https://github.com/readmeio/api/issues"
   },
@@ -32,9 +29,16 @@
   "engines": {
     "node": ">=14"
   },
+  "keywords": [
+    "api",
+    "openapi",
+    "sdk",
+    "swagger"
+  ],
   "dependencies": {
     "@readme/oas-to-har": "^17.0.8",
     "@readme/openapi-parser": "^2.2.0",
+    "caseless": "^0.12.0",
     "chalk": "^4.1.2",
     "commander": "^9.2.0",
     "datauri": "^4.1.0",
@@ -47,21 +51,22 @@
     "get-stream": "^6.0.1",
     "isomorphic-fetch": "^3.0.0",
     "js-yaml": "^4.1.0",
-    "json-schema-to-typescript": "^11.0.1",
+    "json-schema-to-typescript": "^10.1.5",
     "json-schema-traverse": "^1.0.0",
     "lodash.merge": "^4.6.2",
     "make-dir": "^3.1.0",
-    "oas": "^18.3.3",
+    "oas": "^18.3.4",
     "object-hash": "^3.0.0",
     "ora": "^5.4.1",
     "prompts": "^2.4.2",
+    "remove-undefined-objects": "^2.0.1",
     "ssri": "^9.0.0",
     "ts-morph": "^15.1.0",
     "validate-npm-package-name": "^4.0.0"
   },
   "devDependencies": {
-    "@readme/eslint-config": "^8.7.3",
     "@readme/oas-examples": "^5.4.1",
+    "@types/caseless": "^0.12.2",
     "@types/chai": "^4.3.1",
     "@types/find-cache-dir": "^3.2.1",
     "@types/js-yaml": "^4.0.5",
@@ -73,15 +78,13 @@
     "@types/ssri": "^7.1.1",
     "@types/validate-npm-package-name": "^4.0.0",
     "chai": "^4.3.6",
-    "eslint": "^8.14.0",
     "fetch-mock": "^9.11.0",
     "mocha": "^10.0.0",
     "mock-require": "^3.0.3",
     "nyc": "^15.1.0",
-    "prettier": "^2.6.2",
     "sinon": "^14.0.0",
     "sinon-chai": "^3.7.0",
-    "typescript": "^4.6.4",
+    "typescript": "^4.7.4",
     "unique-temp-dir": "^1.0.0"
   },
   "prettier": "@readme/eslint-config/prettier",
@@ -91,5 +94,5 @@
       "test/"
     ]
   },
-  "gitHead": "d18f7e3a1c20edaf84d0c5c2e1a64714549a4ee6"
+  "gitHead": "24d5b83545735176786d212a69121a029cf6dea1"
 }

package/src/cache.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 OpenAPIParser from '@readme/openapi-parser';

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

@@ -1,6 +1,6 @@
 import type Oas from 'oas';
 import type { Operation } from 'oas';
-import type { HttpMethods, JSONSchema, SchemaObject } from 'oas/@types/rmoas.types';
+import type { HttpMethods, JSONSchema, SchemaObject } from 'oas/dist/rmoas.types';
 import type {
   ClassDeclaration,
   JSDocStructure,
@@ -8,6 +8,7 @@ import type {
   OptionalKind,
   ParameterDeclarationStructure,
   TypeParameterDeclarationStructure,
+  VariableStatement,
 } from 'ts-morph';
 import type { Options as JSONSchemaToTypescriptOptions } from 'json-schema-to-typescript';
 import type Storage from '../../storage';
@@ -18,11 +19,16 @@ import path from 'path';
 import CodeGeneratorLanguage from '../language';
 import logger from '../../logger';
 import objectHash from 'object-hash';
-import { IndentationText, Project, QuoteKind, ScriptTarget } from 'ts-morph';
+import { IndentationText, Project, QuoteKind, ScriptTarget, VariableDeclarationKind } from 'ts-morph';
 import { compile } from 'json-schema-to-typescript';
 import { format as prettier } from 'json-schema-to-typescript/dist/src/formatter';
 import execa from 'execa';
 
+export type TSGeneratorOptions = {
+  outputJS?: boolean;
+  compilerTarget?: 'cjs' | 'esm';
+};
+
 type OperationTypeHousing = {
   types: {
     params?: false | Record<'body' | 'formData' | 'metadata', string>;
@@ -51,6 +57,8 @@ export default class TSGenerator extends CodeGeneratorLanguage {
 
   sdk: ClassDeclaration;
 
+  sdkExport: VariableStatement;
+
   schemas: Map<
     string,
     {
@@ -60,15 +68,7 @@ export default class TSGenerator extends CodeGeneratorLanguage {
     }
   >;
 
-  constructor(
-    spec: Oas,
-    specPath: string,
-    identifier: string,
-    opts: {
-      outputJS?: boolean;
-      compilerTarget?: 'cjs' | 'esm';
-    } = {}
-  ) {
+  constructor(spec: Oas, specPath: string, identifier: string, opts: TSGeneratorOptions = {}) {
     const options: { outputJS: boolean; compilerTarget: 'cjs' | 'esm' } = {
       outputJS: false,
       compilerTarget: 'cjs',
@@ -100,9 +100,9 @@ export default class TSGenerator extends CodeGeneratorLanguage {
       },
       compilerOptions: {
         declaration: true,
+        outDir: 'dist',
         resolveJsonModule: true,
         target: options.compilerTarget === 'cjs' ? ScriptTarget.ES5 : ScriptTarget.ES2020,
-        outDir: 'dist',
 
         // If we're compiling to a CJS target then we need to include this compiler option
         // otherwise TS will attempt to load our `openapi.json` import with a `.default` property
@@ -186,23 +186,57 @@ export default class TSGenerator extends CodeGeneratorLanguage {
       name: 'SDK',
     });
 
-    // There's an annoying quirk with `ts-morph` where if we set the SDK class to be the default
-    // export with `isDefaultExport` then when we compile it to an ES5 target for CJS environments
-    // it'll be exported as `export.default = SDK`, which when you try to load it you'll need to
-    // run `require('@api/sdk').default`.
-    //
-    // Instead here by plainly creating the SDK class in the source file and then setting this
-    // export assignment it'll export the SDK class as `module.exports = SDK` so people can cleanly
-    // load the SDK with `require('@api/sdk)`.
-    //
-    // A whole lot of debugging went into here to let people not have to worry about `.default`
-    // messes. I hope it's worth it!
+    this.sdkExport = sdkSource.addVariableStatement({
+      declarationKind: VariableDeclarationKind.Const,
+      declarations: [
+        {
+          name: 'createSDK',
+          initializer: writer => {
+            // `ts-morph` doesn't have any way to cleanly create an IFEE.
+            writer.writeLine('(() => { return new SDK(); })()');
+            return writer;
+          },
+        },
+      ],
+    });
+
+    /**
+     * There's an annoying quirk with `ts-morph` where if we set the `createSDK` function to be the
+     * default export with `isDefaultExport` then when we compile it to an ES5 target for CJS
+     * environments it'll be exported as `export.default = createSDK`, which when you try to load it
+     * you'll need to run `require('@api/sdk').default`.
+     *
+     * Instead here by plainly creating `createSDK` in the source file and then setting this export
+     * assignment it'll export the SDK IFEE initializer as `module.exports = createSDK` so people
+     * can cleanly load their SDK with `require('@api/sdk)`.
+     *
+     * A whole lot of debugging went into here to let people not have to worry about `.default`
+     * messes. I hope it's worth it!
+     */
     if (this.compilerTarget === 'cjs') {
       sdkSource.addExportAssignment({
-        expression: 'SDK',
+        expression: 'createSDK',
       });
     } else {
-      this.sdk.setIsDefaultExport(true);
+      /**
+       * Because `createSDK` above is an IFEE constant we can't use `setIsDefaultExport` on it due
+       * to `ts-morph` not having great handling for IFEE's.
+       *
+       * If we were to call `setIsDefaultExport` on our IFEE to attempt to compile it as
+       * `export default createSDK` then `ts-morph` hard crashes with a "Error replacing tree: The
+       * children of the old and new trees were expected to have the same count" exception due to
+       * it not being able properly handle IFEE's. It's for that reason that we need to manually
+       * write a statement expression to set `createSDK` as the default export.
+       *
+       * Another quirk that this work avoids is there being an empty `export {};` at the very end
+       * of our compiled `d.ts` declaration file. I'm not sure why it was being added, and it
+       * didn't appear to be harming anything, but us manually creating this export statement
+       * causes it to go away.
+       *
+       * Thankfully, fortunately, and curiously, these are all only problems in non-CJS compiled
+       * targets. ¯\_(ツ)_/¯
+       */
+      sdkSource.addStatements('export default createSDK');
     }
 
     this.sdk.addProperties([
@@ -334,7 +368,43 @@ sdk.server('https://eu.api.example.com/v14');`)
     // @todo should all of these isolated into their own file outside of the main sdk class file?
     // Add all known types that we're using into the SDK.
     Array.from(this.types.values()).forEach(exp => {
-      sdkSource.addStatements(exp);
+      /**
+       * When `ts-morph` compiles declaration files when we're targeting CJS environments it creates
+       * the default export as `export = _default` instead of `export default const _default`. This
+       * causes TS to throw a TS2309 error for "An export assignment cannot be used in a module
+       * with other exported elements" because our types and interfaces are also being exported and
+       * the `export =` overrides those.
+       *
+       * Fixing this is, to be frank, a fucking HARD problem for a couple reasons:
+       *
+       *  1. Our JSON Schema types and interfaces are coming from `json-schema-to-typescript` and
+       *    that library exports its data a raw string containing multiple types and interfaces.
+       *    The only way we're able to capture and use them in our codegenerated SDK is because
+       *    we're ingesting that string into `ts-morph` and then using its APIs to extract exported
+       *    declarations (which are still strings) and then they're re-inserted into our main
+       *    source file here.
+       *  2. Though `ts-morph` has APIs for adding type aliases and interfaces to a source file what
+       *    it doesn't have is the ability to pass in a string, or a `Writer` class that exposes,
+       *    to write raw strings to a type or an interface. If it did we'd be able to replace this
+       *    `addStatements` call with an `addTypeAlias` and `addInterface` call for each of our
+       *    JSON Schema schemas that we've got along with an `isExported` flag for `ts-morph` to
+       *    export it.
+       *
+       * Because neither of these are solvable problems right now we're instead opting to **not**
+       * export types and interfaces from these SDKs. This isn't a great solution because it
+       * /slightly/ reduces the usability of the TS codegen functionality but in order for the TS
+       * declaration files that we generate to be valid this is the only option that we've got.
+       *
+       * However, that said, if somebody needs an interface or type exported they can export it
+       * themselves in the SDK code that we compile for them.
+       *
+       * @fixme
+       */
+      sdkSource.addStatements(
+        // All expressions coming out of `json-schema-to-typescript` are exported so by popping this
+        // off we'll just be inserting plain interfaces and types into the SDK source.
+        exp.substring('export '.length)
+      );
     });
 
     if (this.outputJS) {
@@ -373,7 +443,7 @@ sdk.server('https://eu.api.example.com/v14');`)
     const parameters: OptionalKind<ParameterDeclarationStructure>[] = [{ name: 'path', type: 'string' }];
     const docblock: OptionalKind<JSDocStructure> = {
       description: writer => {
-        writer.writeLine(`Access any ${method} endpoint on your API.`);
+        writer.writeLine(`Access any ${method.toUpperCase()} endpoint on your API.`);
         return writer;
       },
       tags: [{ tagName: 'param', text: 'path API path to make a request against.' }],
@@ -589,7 +659,7 @@ sdk.server('https://eu.api.example.com/v14');`)
         this.methodGenerics.get(operation.method).addOverload({
           typeParameters,
           parameters: [
-            { name: 'path', type: 'string' },
+            { name: 'path', type: `'${operation.path}'` },
             { ...parameters.body, hasQuestionToken: false },
             { ...parameters.metadata, hasQuestionToken: false },
           ],
@@ -600,14 +670,14 @@ sdk.server('https://eu.api.example.com/v14');`)
         // Create an overload that just has a single `metadata` parameter.
         this.methodGenerics.get(operation.method).addOverload({
           typeParameters,
-          parameters: [{ name: 'path', type: 'string' }, parameters.metadata],
+          parameters: [{ name: 'path', type: `'${operation.path}'` }, parameters.metadata],
           returnType,
           docs: docblock ? [docblock] : null,
         });
       } else {
         this.methodGenerics.get(operation.method).addOverload({
           typeParameters: responseTypes ? null : ['T = unknown'],
-          parameters: [{ name: 'path', type: 'string' }, ...Object.values(parameters)],
+          parameters: [{ name: 'path', type: `'${operation.path}'` }, ...Object.values(parameters)],
           returnType,
           docs: docblock ? [docblock] : null,
         });
@@ -673,12 +743,17 @@ sdk.server('https://eu.api.example.com/v14');`)
       Object.entries(ops).forEach(([method, operation]: [HttpMethods, Operation]) => {
         methods.add(method);
 
-        const operationId = operation.getOperationId();
+        const operationId = operation.getOperationId({
+          // This `camelCase` option will clean up any weird characters that might be present in
+          // the `operationId` so as we don't break TS compilation with an invalid method accessor.
+          camelCase: true,
+        });
+
         const params = this.prepareParameterTypesForOperation(operation, operationId);
         const responses = this.prepareResponseTypesForOperation(operation, operationId);
 
         if (operation.hasOperationId()) {
-          operations[operation.getOperationId()] = {
+          operations[operationId] = {
             types: {
               params,
               responses,
@@ -758,8 +833,12 @@ sdk.server('https://eu.api.example.com/v14');`)
    * @param operationId
    */
   prepareResponseTypesForOperation(operation: Operation, operationId: string) {
-    const schemas = operation
-      .getResponseStatusCodes()
+    const responseStatusCodes = operation.getResponseStatusCodes();
+    if (!responseStatusCodes.length) {
+      return undefined;
+    }
+
+    const schemas = responseStatusCodes
       .map(status => {
         const schema = operation.getResponseAsJsonSchema(status);
         if (!schema) {

package/src/cli/storage.ts

@@ -1,4 +1,4 @@
-import type { OASDocument } from 'oas/@types/rmoas.types';
+import type { OASDocument } from 'oas/dist/rmoas.types';
 
 import ssri from 'ssri';
 import fs from 'fs';

package/src/core/getJSONSchemaDefaults.ts

@@ -1,5 +1,5 @@
-import type { SchemaObject } from 'oas/@types/rmoas.types';
-import type { SchemaWrapper } from 'oas/@types/operation/get-parameters-as-json-schema';
+import type { SchemaObject } from 'oas/dist/rmoas.types';
+import type { SchemaWrapper } from 'oas/dist/operation/get-parameters-as-json-schema';
 import traverse from 'json-schema-traverse';
 
 /**

package/src/core/index.ts

@@ -1,6 +1,6 @@
 import type Oas from 'oas';
 import type { Operation } from 'oas';
-import type { HttpMethods } from 'oas/@types/rmoas.types';
+import type { HttpMethods } from 'oas/dist/rmoas.types';
 
 import 'isomorphic-fetch';
 import fetchHar from 'fetch-har';

package/src/core/prepareParams.ts

@@ -1,5 +1,5 @@
 import type { Operation } from 'oas';
-import type { ParameterObject, SchemaObject } from 'oas/@types/rmoas.types';
+import type { ParameterObject, SchemaObject } from 'oas/dist/rmoas.types';
 import type { ReadStream } from 'fs';
 
 import lodashMerge from 'lodash.merge';
@@ -9,6 +9,8 @@ import stream from 'stream';
 import getStream from 'get-stream';
 import datauri from 'datauri/sync';
 import DatauriParser from 'datauri/parser';
+import removeUndefinedObjects from 'remove-undefined-objects';
+import caseless from 'caseless';
 import getJSONSchemaDefaults from './getJSONSchemaDefaults';
 
 /**
@@ -22,7 +24,7 @@ import getJSONSchemaDefaults from './getJSONSchemaDefaults';
 function digestParameters(parameters: ParameterObject[]): Record<string, ParameterObject> {
   return parameters.reduce((prev, param) => {
     if ('$ref' in param || 'allOf' in param || 'anyOf' in param || 'oneOf' in param) {
-      throw new Error(`The OpenAPI document for this operation wasn't dereferenced before processing.`);
+      throw new Error("The OpenAPI document for this operation wasn't dereferenced before processing.");
     } else if (param.name in prev) {
       throw new Error(
         `The operation you are using has the same parameter, ${param.name}, spread across multiple entry points. We unfortunately can't handle this right now.`
@@ -123,7 +125,7 @@ function processFile(
     new TypeError(
       paramName
         ? `The data supplied for the \`${paramName}\` request body parameter is not a file handler that we support.`
-        : `The data supplied for the request body payload is not a file handler that we support.`
+        : 'The data supplied for the request body payload is not a file handler that we support.'
     )
   );
 }
@@ -143,6 +145,18 @@ export default async function prepareParams(operation: Operation, body?: unknown
   const hasDigestedParams = !!Object.keys(digestedParameters).length;
   const jsonSchema = operation.getParametersAsJsonSchema();
 
+  /**
+   * It might be common for somebody to run `sdk.findPetsByStatus({ status: 'available' }, {})`, in
+   * which case we want to filter out the second (metadata) parameter and treat the first parameter
+   * as the metadata instead. If we don't do this, their supplied `status` metadata will be treated
+   * as a body parameter, and because there's no `status` body parameter, and no supplied metadata
+   * (because it's an empty object), the request won't send a payload.
+   *
+   * @see {@link https://github.com/readmeio/api/issues/449}
+   */
+  // eslint-disable-next-line no-param-reassign
+  metadata = removeUndefinedObjects(metadata);
+
   if (!jsonSchema && (body !== undefined || metadata !== undefined)) {
     throw new Error(
       "You supplied metadata and/or body data for this operation but it doesn't have any documented parameters or request payloads. If you think this is an error please contact support for the API you're using."
@@ -184,7 +198,25 @@ export default async function prepareParams(operation: Operation, body?: unknown
         // isn't anything we can do about it.
         params.body = merge(params.body, body);
       } else {
-        const intersection = Object.keys(body).filter(value => Object.keys(digestedParameters).includes(value)).length;
+        const headerParams = caseless({});
+        Object.entries(digestedParameters).forEach(([paramName, param]) => {
+          // Headers are sent case-insensitive so we need to make sure that we're properly
+          // matching them when detecting what our incoming payload looks like.
+          if (param.in === 'header') {
+            headerParams.set(paramName, '');
+          }
+        });
+
+        const intersection = Object.keys(body).filter(value => {
+          if (Object.keys(digestedParameters).includes(value)) {
+            return true;
+          } else if (headerParams.has(value)) {
+            return true;
+          }
+
+          return false;
+        }).length;
+
         if (intersection && intersection / Object.keys(body).length > 0.25) {
           /* eslint-disable no-param-reassign */
           // If more than 25% of the body intersects with the parameters that we've got on hand,
@@ -276,8 +308,14 @@ export default async function prepareParams(operation: Operation, body?: unknown
 
     Object.entries(digestedParameters).forEach(([paramName, param]) => {
       let value: any;
-      if (typeof metadata === 'object' && !isEmpty(metadata) && paramName in metadata) {
-        value = metadata[paramName];
+      if (typeof metadata === 'object' && !isEmpty(metadata)) {
+        if (paramName in metadata) {
+          value = metadata[paramName];
+        } else if (param.in === 'header') {
+          // Headers are sent case-insensitive so we need to make sure that we're properly
+          // matching them when detecting what our incoming payload looks like.
+          value = metadata[Object.keys(metadata).find(k => k.toLowerCase() === paramName.toLowerCase())];
+        }
       }
 
       if (value === undefined) {
@@ -295,7 +333,7 @@ export default async function prepareParams(operation: Operation, body?: unknown
           delete metadata[paramName];
           break;
         case 'header':
-          params.header[paramName] = value;
+          params.header[paramName.toLowerCase()] = value;
           delete metadata[paramName];
           break;
         case 'cookie':

package/src/fetcher.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 OpenAPIParser from '@readme/openapi-parser';
@@ -18,10 +18,21 @@ export default class Fetcher {
 
   constructor(uri: string | OASDocument) {
     if (typeof uri === 'string') {
-      // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
-      this.uri = Fetcher.isAPIRegistryUUID(uri)
-        ? uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4')
-        : uri;
+      if (Fetcher.isAPIRegistryUUID(uri)) {
+        // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
+        this.uri = uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4');
+      } else if (Fetcher.isGitHubBlobURL(uri)) {
+        /**
+         * People may try to use a public repository URL to the source viewer on GitHub not knowing
+         * that this page actually serves HTML. In this case we want to rewrite these to the "raw"
+         * version of this page that'll allow us to access the API definition.
+         *
+         * @example https://github.com/readmeio/oas-examples/blob/main/3.1/json/petstore.json
+         */
+        this.uri = uri.replace(/\/\/github.com/, '//raw.githubusercontent.com').replace(/\/blob\//, '/');
+      } else {
+        this.uri = uri;
+      }
     } else {
       this.uri = uri;
     }
@@ -31,6 +42,10 @@ export default class Fetcher {
     return Fetcher.registryUUIDRegex.test(uri);
   }
 
+  static isGitHubBlobURL(uri: string) {
+    return /\/\/github.com\/[-_a-zA-Z0-9]+\/[-_a-zA-Z0-9]+\/blob\/(.*).(yaml|json|yml)/.test(uri);
+  }
+
   static getProjectPrefixFromRegistryUUID(uri: string) {
     const matches = uri.match(Fetcher.registryUUIDRegex);
     if (!matches) {

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { Operation } from 'oas';
-import type { HttpMethods, OASDocument } from 'oas/@types/rmoas.types';
+import type { HttpMethods, OASDocument } from 'oas/dist/rmoas.types';
 import type { ConfigOptions } from './core';
 
 import Oas from 'oas';

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 = '5.0.0-beta.0';
+export const PACKAGE_VERSION = '5.0.0-beta.3';