api 4.3.0 → 4.5.1

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.3.0",
+  "version": "4.5.1",
   "description": "Generate an SDK from an OpenAPI definition",
   "main": "src/index.js",
   "scripts": {
@@ -48,8 +48,9 @@
   "prettier": "@readme/eslint-config/prettier",
   "jest": {
     "testPathIgnorePatterns": [
-      "__tests__/__fixtures__/"
+      "__tests__/__fixtures__/",
+      ".api-test/"
     ]
   },
-  "gitHead": "d69e58465d8eff63aec29693f70d085247afb7ef"
+  "gitHead": "5c3490291498c1ac7f2f9dfe2ad99afff9010689"
 }

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');
 
@@ -87,7 +92,18 @@ class SdkCache {
     }
 
     const cache = this.getCache();
-    return JSON.parse(fs.readFileSync(cache[this.uriHash].path, 'utf8'));
+
+    // Prior to v4.5.0 we were putting a fully resolved path to the API definition in the cache
+    // store but if you had specified a custom caching directory and would generate the cache on
+    // your system, that filepath would obviously not be the same in other environments. For this
+    // reason the `path` was removed from the cache store in favor of storing the `hash` instead.
+    //
+    // If we still have `path` in the config cache for backwards compatibility we should use it.
+    if ('path' in cache[this.uriHash]) {
+      return JSON.parse(fs.readFileSync(cache[this.uriHash].path, 'utf8'));
+    }
+
+    return JSON.parse(fs.readFileSync(path.join(this.specsCache, `${cache[this.uriHash].hash}.json`)));
   }
 
   async load() {
@@ -154,16 +170,16 @@ class SdkCache {
         const cache = self.getCache();
         if (!(self.uriHash in cache)) {
           const saved = JSON.stringify(spec, null, 2);
-          const jsonHash = crypto.createHash('md5').update(saved).digest('hex');
+          const fileHash = crypto.createHash('md5').update(saved).digest('hex');
 
           cache[self.uriHash] = {
-            path: path.join(self.specsCache, `${jsonHash}.json`),
+            hash: fileHash,
             original: self.uri,
             title: 'title' in spec.info ? spec.info.title : undefined,
             version: 'version' in spec.info ? spec.info.version : undefined,
           };
 
-          fs.writeFileSync(cache[self.uriHash].path, saved);
+          fs.writeFileSync(path.join(self.specsCache, `${fileHash}.json`), saved);
           fs.writeFileSync(self.cacheStore, JSON.stringify(cache, null, 2));
 
           self.cache = cache;
@@ -206,4 +222,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/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;
 };