api 4.2.1 → 4.5.0

package/README.md

@@ -23,9 +23,9 @@ npm install api --save
 Using `api` is as simple as supplying it an OpenAPI and using the SDK as you would any other!
 
 ```js
-const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas/master/packages/examples/3.0/json/petstore.json');
+const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json');
 
-sdk.listPets().then(res => res.json()).then(res => {
+sdk.listPets().then(res => {
   console.log(`My pets name is ${res[0].name}!`);
 });
 ```
@@ -33,10 +33,11 @@ sdk.listPets().then(res => res.json()).then(res => {
 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 that you can chain to your requests, as such:
+`api` supports API authentication through an `.auth()` method:
 
 ```js
-sdk.auth('myApiToken').listPets().then(...);
+sdk.auth('myApiToken');
+sdk.listPets().then(...);
 ```
 
 With the exception of OpenID, it supports all forms of authentication supported by the OpenAPI specification! Just give `.auth()` your credentials and it'll figure out how to use it according to the API you're using.
@@ -47,6 +48,8 @@ For example:
 * Bearer tokens (HTTP or OAuth 2): `sdk.auth('myBearerToken')`
 * API Keys: `sdk.auth('myApiKey')`
 
+> ℹ️ Note that `sdk.auth()` is not chainable.
+
 ### 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:
 
@@ -161,3 +164,17 @@ By default we parse the response based on the `content-type` header for you. You
 ```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 => {
+  console.log(`My pets name is ${res[0].name}!`);
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api",
-  "version": "4.2.1",
+  "version": "4.5.0",
   "description": "Generate an SDK from an OpenAPI definition",
   "main": "src/index.js",
   "scripts": {
@@ -23,8 +23,8 @@
     "node": "^12 || ^14 || ^16"
   },
   "dependencies": {
-    "@readme/oas-to-har": "^14.0.5",
-    "@readme/openapi-parser": "^2.0.0",
+    "@readme/oas-to-har": "^16.1.0",
+    "@readme/openapi-parser": "^2.1.0",
     "datauri": "^4.1.0",
     "fetch-har": "^5.0.5",
     "find-cache-dir": "^3.3.1",
@@ -34,7 +34,7 @@
     "make-dir": "^3.1.0",
     "mimer": "^2.0.2",
     "node-fetch": "^2.6.0",
-    "oas": "^17.4.1"
+    "oas": "^18.1.0"
   },
   "devDependencies": {
     "@readme/eslint-config": "^8.0.2",
@@ -48,8 +48,9 @@
   "prettier": "@readme/eslint-config/prettier",
   "jest": {
     "testPathIgnorePatterns": [
-      "__tests__/__fixtures__/"
+      "__tests__/__fixtures__/",
+      ".api-test/"
     ]
   },
-  "gitHead": "0cdb386e34d37de51ce8909f5dc9c4cd338ef4de"
+  "gitHead": "2cbe023cb5d2c1ff1f8b46a4c90d49bb7af0c5f1"
 }

package/src/cache.js

@@ -9,18 +9,8 @@ const os = require('os');
 const path = require('path');
 const makeDir = require('make-dir');
 
-let cacheDir = findCacheDir({ name: pkg.name });
-if (typeof cacheDir === 'undefined') {
-  // The `find-cache-dir` module returns `undefined` if the `node_modules/` directory isn't writable, or there's no
-  // `package.json` in the root-most directory. If this happens, we can instead adhoc create a cache directory in the
-  // users OS temp directory and store our data there.
-  //
-  // @link https://github.com/avajs/find-cache-dir/issues/29
-  cacheDir = makeDir.sync(path.join(os.tmpdir(), pkg.name));
-}
-
-class SdkCache {
-  constructor(uri) {
+class Cache {
+  constructor(uri, cacheDir = false) {
     /**
      * Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
      *
@@ -37,8 +27,23 @@ class SdkCache {
         : u;
 
     this.uri = resolveReadMeRegistryAccessor(uri);
-    this.uriHash = SdkCache.getCacheHash(this.uri);
-    this.dir = cacheDir;
+    this.uriHash = Cache.getCacheHash(this.uri);
+
+    if (cacheDir) {
+      this.dir = cacheDir;
+    } else {
+      this.dir = findCacheDir({ name: pkg.name });
+      if (typeof this.dir === 'undefined') {
+        // The `find-cache-dir` module returns `undefined` if the `node_modules/` directory isn't
+        // writable, or there's no `package.json` in the root-most directory. If this happens, we
+        // can instead adhoc create a cache directory in the users OS temp directory and store our
+        // data there.
+        //
+        // @link https://github.com/avajs/find-cache-dir/issues/29
+        this.dir = makeDir.sync(path.join(os.tmpdir(), pkg.name));
+      }
+    }
+
     this.cacheStore = path.join(this.dir, 'cache.json');
     this.specsCache = path.join(this.dir, 'specs');
 
@@ -206,4 +211,4 @@ class SdkCache {
   }
 }
 
-module.exports = SdkCache;
+module.exports = Cache;

package/src/index.js

@@ -13,9 +13,11 @@ global.Headers = fetch.Headers;
 global.FormData = require('form-data');
 
 class Sdk {
-  constructor(uri) {
+  constructor(uri, opts = {}) {
     this.uri = uri;
     this.userAgent = `${pkg.name} (node)/${pkg.version}`;
+
+    this.cacheDir = opts.cacheDir ? opts.cacheDir : false;
   }
 
   static getOperations(spec) {
@@ -29,8 +31,8 @@ class Sdk {
   }
 
   load() {
-    const authKeys = [];
-    const cache = new Cache(this.uri);
+    let authKeys = [];
+    const cache = new Cache(this.uri, this.cacheDir);
     const self = this;
     let config = { parseResponse: true };
     let server = false;
@@ -150,8 +152,7 @@ class Sdk {
 
     sdk = {
       auth: (...values) => {
-        authKeys.push(values);
-        return new Proxy(sdk, sdkProxy);
+        authKeys = values;
       },
       config: opts => {
         // Downside to having `opts` be merged into the existing `config` is that there isn't a clean way to reset your
@@ -171,6 +172,6 @@ class Sdk {
   }
 }
 
-module.exports = uri => {
-  return new Sdk(uri).load();
+module.exports = (uri, opts = {}) => {
+  return new Sdk(uri, opts).load();
 };

package/src/lib/getSchema.js

@@ -0,0 +1,34 @@
+const {
+  utils: { findSchemaDefinition },
+} = require('oas');
+
+// Gets the schema of the first media type defined in the `content` of the path operation
+// or returns the ref if there's no Request Body Object.
+//
+// If the ref looks like a `requestBodies` reference, then do a lookup for the actual schema
+// https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-8
+module.exports = function getSchema(pathOperation, api) {
+  try {
+    if (pathOperation.requestBody.content) {
+      const type = Object.keys(pathOperation.requestBody.content)[0];
+
+      return {
+        type,
+        schema: pathOperation.requestBody.content[type],
+      };
+    }
+
+    if (pathOperation.requestBody && pathOperation.requestBody.$ref.match(/^#\/components\/requestBodies\/.*$/)) {
+      return getSchema({
+        requestBody: findSchemaDefinition(pathOperation.requestBody.$ref, api),
+      });
+    }
+
+    return {
+      type: 'application/json',
+      schema: pathOperation.requestBody,
+    };
+  } catch (e) {} // eslint-disable-line no-empty
+
+  return undefined;
+};

package/src/lib/prepareAuth.js

@@ -7,8 +7,8 @@
  * @param {Array} authKeys
  * @param {Operation} operation
  */
-module.exports = (authKeys, operation) => {
-  if (authKeys.length === 0) {
+module.exports = (authKey, operation) => {
+  if (authKey.length === 0) {
     return {};
   }
 
@@ -21,31 +21,20 @@ module.exports = (authKeys, operation) => {
     return {};
   }
 
-  authKeys.forEach((authKey, idx) => {
-    const schemes = security[securitySchemes[idx]];
-    if (schemes.length > 1) {
-      throw new Error(
-        `Sorry, this API currently requires multiple forms of authentication which we don't yet support.`
-      );
-    }
-
-    const scheme = schemes[0];
-    if (scheme.type === 'http') {
-      if (scheme.scheme === 'basic') {
-        prepared[scheme._key] = {
-          user: authKey[0],
-          pass: authKey.length === 2 ? authKey[1] : '',
-        };
-      } else if (scheme.scheme === 'bearer') {
-        if (authKey.length > 1) {
-          throw new Error(
-            'Multiple auth tokens were supplied for the auth on this endpoint, but only a single token is needed.'
-          );
-        }
+  const securityType = securitySchemes[0];
+  const schemes = security[securityType];
+  if (schemes.length > 1) {
+    throw new Error("Sorry, this API currently requires multiple forms of authentication which we don't yet support.");
+  }
 
-        prepared[scheme._key] = authKey[0];
-      }
-    } else if (scheme.type === 'oauth2') {
+  const scheme = schemes[0];
+  if (scheme.type === 'http') {
+    if (scheme.scheme === 'basic') {
+      prepared[scheme._key] = {
+        user: authKey[0],
+        pass: authKey.length === 2 ? authKey[1] : '',
+      };
+    } else if (scheme.scheme === 'bearer') {
       if (authKey.length > 1) {
         throw new Error(
           'Multiple auth tokens were supplied for the auth on this endpoint, but only a single token is needed.'
@@ -53,20 +42,28 @@ module.exports = (authKeys, operation) => {
       }
 
       prepared[scheme._key] = authKey[0];
-    } else if (scheme.type === 'apiKey') {
-      if (authKey.length > 1) {
-        throw new Error(
-          'Multiple auth keys were supplied for the auth on this endpoint, but only a single key is needed.'
-        );
-      }
+    }
+  } else if (scheme.type === 'oauth2') {
+    if (authKey.length > 1) {
+      throw new Error(
+        'Multiple auth tokens were supplied for the auth on this endpoint, but only a single token is needed.'
+      );
+    }
 
-      if (scheme.in === 'query' || scheme.in === 'header') {
-        prepared[scheme._key] = authKey[0];
-      }
-    } else {
-      throw new Error(`Sorry, this API currently supports a scheme, ${scheme.type}, that we don't yet support.`);
+    prepared[scheme._key] = authKey[0];
+  } else if (scheme.type === 'apiKey') {
+    if (authKey.length > 1) {
+      throw new Error(
+        'Multiple auth keys were supplied for the auth on this endpoint, but only a single key is needed.'
+      );
     }
-  });
+
+    if (scheme.in === 'query' || scheme.in === 'header') {
+      prepared[scheme._key] = authKey[0];
+    }
+  } else {
+    throw new Error(`Sorry, this API currently supports a scheme, ${scheme.type}, that we don't yet support.`);
+  }
 
   return prepared;
 };

package/src/lib/prepareParams.js

@@ -4,9 +4,7 @@ const stream = require('stream');
 const mimer = require('mimer');
 const getStream = require('get-stream');
 const datauri = require('datauri');
-const {
-  utils: { getSchema },
-} = require('oas');
+const getSchema = require('./getSchema');
 
 function digestParameters(parameters) {
   return parameters.reduce((prev, param) => {