api 5.0.0-beta.2 → 5.0.0

package/src/cli/commands/install.ts

@@ -1,18 +1,16 @@
 import type { SupportedLanguages } from '../codegen';
 
 import { Command, Option } from 'commander';
-import ora from 'ora';
+import figures from 'figures';
 import Oas from 'oas';
+import ora from 'ora';
+import validateNPMPackageName from 'validate-npm-package-name';
 
-import codegen from '../codegen';
 import Fetcher from '../../fetcher';
-import Storage from '../storage';
-import logger from '../logger';
-
+import codegen from '../codegen';
 import promptTerminal from '../lib/prompt';
-
-import figures from 'figures';
-import validateNPMPackageName from 'validate-npm-package-name';
+import logger from '../logger';
+import Storage from '../storage';
 
 // @todo log logs to `.api/.logs` and have `.logs` ignored
 const cmd = new Command();

package/src/cli/storage.ts

@@ -1,13 +1,13 @@
-import type { OASDocument } from 'oas/@types/rmoas.types';
+import type { OASDocument } from 'oas/dist/rmoas.types';
 
-import ssri from 'ssri';
 import fs from 'fs';
 import path from 'path';
-import makeDir from 'make-dir';
 
-import { PACKAGE_VERSION } from '../packageInfo';
+import makeDir from 'make-dir';
+import ssri from 'ssri';
 
 import Fetcher from '../fetcher';
+import { PACKAGE_VERSION } from '../packageInfo';
 
 export default class Storage {
   static dir: string;

package/src/core/errors/fetchError.ts

@@ -0,0 +1,31 @@
+class FetchError extends Error {
+  /** HTTP Status */
+  status: number;
+
+  /** The content of the response. */
+  data: unknown;
+
+  /** The Headers of the response. */
+  headers: Headers;
+
+  /** The raw `Response` object. */
+  res: Response;
+
+  constructor(status: number, data: unknown, headers: Headers, res: Response) {
+    super(res.statusText);
+
+    this.name = 'FetchError';
+    this.status = status;
+    this.data = data;
+    this.headers = headers;
+    this.res = res;
+
+    // We could fix this by updating our target to ES2015 but because we support exporting to CJS
+    // we can't.
+    //
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, FetchError.prototype);
+  }
+}
+
+export default FetchError;

package/src/core/getJSONSchemaDefaults.ts

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

package/src/core/index.ts

@@ -1,12 +1,15 @@
 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';
 import oasToHar from '@readme/oas-to-har';
+import fetchHar from 'fetch-har';
 import { FormDataEncoder } from 'form-data-encoder';
+import 'isomorphic-fetch';
+// `AbortController` was shipped in Node 15 so when Node 14 is EOL'd we can drop this dependency.
+import { AbortController } from 'node-abort-controller';
 
+import FetchError from './errors/fetchError';
 import getJSONSchemaDefaults from './getJSONSchemaDefaults';
 import parseResponse from './parseResponse';
 import prepareAuth from './prepareAuth';
@@ -15,12 +18,26 @@ import prepareServer from './prepareServer';
 
 export interface ConfigOptions {
   /**
-   * By default we parse the response based on the `Content-Type` header of the request. You can
-   * disable this functionality by negating this option.
+   * Override the default `fetch` request timeout of 30 seconds. This number should be represented
+   * in milliseconds.
    */
-  parseResponse: boolean;
+  timeout?: number;
 }
 
+export type FetchResponse<status, data> = {
+  data: data;
+  status: status;
+  headers: Headers;
+  res: Response;
+};
+
+// https://stackoverflow.com/a/39495173
+type Enumerate<N extends number, Acc extends number[] = []> = Acc['length'] extends N
+  ? Acc[number]
+  : Enumerate<N, [...Acc, Acc['length']]>;
+
+export type HTTPMethodRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F>>;
+
 export { getJSONSchemaDefaults, parseResponse, prepareAuth, prepareParams, prepareServer };
 
 export default class APICore {
@@ -35,7 +52,7 @@ export default class APICore {
         variables?: Record<string, string | number>;
       } = false;
 
-  private config: ConfigOptions = { parseResponse: true };
+  private config: ConfigOptions = {};
 
   private userAgent: string;
 
@@ -88,21 +105,39 @@ export default class APICore {
         }
       }
 
+      // @ts-expect-error `this.auth` typing is off. FIXME
       const har = oasToHar(this.spec, operation, data, prepareAuth(this.auth, operation));
 
-      return fetchHar(har, {
-        userAgent: this.userAgent,
+      let timeoutSignal: any;
+      const init: RequestInit = {};
+      if (this.config.timeout) {
+        const controller = new AbortController();
+        timeoutSignal = setTimeout(() => controller.abort(), this.config.timeout);
+        // @todo Typing on `AbortController` coming out of `node-abort-controler` isn't right so when
+        // we eventually drop that dependency we can remove the `as any` here.
+        init.signal = controller.signal as any;
+      }
+
+      return fetchHar(har as any, {
         files: data.files || {},
+        init,
         multipartEncoder: FormDataEncoder,
-      }).then((res: Response) => {
-        if (res.status >= 400 && res.status <= 599) {
-          throw res;
-        }
-
-        if (this.config.parseResponse === false) return res;
-
-        return parseResponse(res);
-      });
+        userAgent: this.userAgent,
+      })
+        .then(async (res: Response) => {
+          const parsed = await parseResponse(res);
+
+          if (res.status >= 400 && res.status <= 599) {
+            throw new FetchError(parsed.status, parsed.data, parsed.headers, parsed.res);
+          }
+
+          return parsed;
+        })
+        .finally(() => {
+          if (this.config.timeout) {
+            clearTimeout(timeoutSignal);
+          }
+        });
     });
   }
 }

package/src/core/parseResponse.ts

@@ -8,13 +8,19 @@ export default async function getResponseBody(response: Response) {
 
   const responseBody = await response.text();
 
+  let data = responseBody;
   if (isJSON) {
     try {
-      return JSON.parse(responseBody);
+      data = JSON.parse(responseBody);
     } catch (e) {
       // If our JSON parsing failed then we can just return plaintext instead.
     }
   }
 
-  return responseBody;
+  return {
+    data,
+    status: response.status,
+    headers: response.headers,
+    res: response,
+  };
 }

package/src/core/prepareAuth.ts

@@ -1,8 +1,6 @@
 /* eslint-disable no-underscore-dangle */
 import type { Operation } from 'oas';
 
-type SecurityType = 'Basic' | 'Bearer' | 'Query' | 'Header' | 'Cookie' | 'OAuth2' | 'http' | 'apiKey';
-
 export default function prepareAuth(authKey: (number | string)[], operation: Operation) {
   if (authKey.length === 0) {
     return {};
@@ -18,25 +16,67 @@ export default function prepareAuth(authKey: (number | string)[], operation: Ope
       }
   > = {};
 
-  const security = operation.prepareSecurity();
-
-  const securitySchemes = Object.keys(security);
-  if (securitySchemes.length === 0) {
+  const security = operation.getSecurity();
+  if (security.length === 0) {
     // If there's no auth configured on this operation, don't prepare anything (even if it was
     // supplied by the user).
     return {};
   }
 
-  const securityType = securitySchemes[0] as SecurityType;
-
-  const schemes = security[securityType];
+  // Does this operation require multiple forms of auth?
+  if (security.every(s => Object.keys(s).length > 1)) {
+    throw new Error(
+      "Sorry, this operation currently requires multiple forms of authentication which this library doesn't yet support."
+    );
+  }
 
-  if (schemes.length > 1) {
-    throw new Error("Sorry, this API currently requires multiple forms of authentication which we don't yet support.");
+  // Since we can only handle single auth security configurations, let's pull those out. This code
+  // is a bit opaque but `security` here may look like `[{ basic: [] }, { oauth2: [], basic: []}]`
+  // and are filtering it down to only single-auth requirements of `[{ basic: [] }]`.
+  const usableSecurity = security
+    .map(s => {
+      return Object.keys(s).length === 1 ? s : false;
+    })
+    .filter(Boolean);
+
+  const usableSecuritySchemes = usableSecurity.map(s => Object.keys(s)).reduce((prev, next) => prev.concat(next), []);
+  const preparedSecurity = operation.prepareSecurity();
+
+  // If we have two auth tokens present let's look for Basic Auth in their configuration.
+  if (authKey.length >= 2) {
+    // If this operation doesn't support HTTP Basic auth but we have two tokens, that's a paddlin.
+    if (!('Basic' in preparedSecurity)) {
+      throw new Error('Multiple auth tokens were supplied for this endpoint but only a single token is needed.');
+    }
+
+    // If we have two auth keys for Basic Auth but Basic isn't a usable security scheme (maybe it's
+    // part of an AND or auth configuration -- which we don't support) then we need to error out.
+    const schemes = preparedSecurity.Basic.filter(s => usableSecuritySchemes.includes(s._key));
+    if (!schemes.length) {
+      throw new Error(
+        'Credentials for Basic Authentication were supplied but this operation requires another form of auth in that case, which this library does not yet support. This operation does, however, allow supplying a single auth token.'
+      );
+    }
+
+    const scheme = schemes.shift();
+    preparedAuth[scheme._key] = {
+      user: authKey[0],
+      pass: authKey.length === 2 ? authKey[1] : '',
+    };
+
+    return preparedAuth;
   }
 
-  const scheme = schemes[0];
+  // If we know we don't need to use HTTP Basic auth because we have a username+password then we
+  // can pick the first usable security scheme available and try to use that. This might not always
+  // be the auth scheme that the user wants, but we don't have any other way for the user to tell
+  // us what they want with the current `sdk.auth()` API.
+  const usableScheme = usableSecuritySchemes[0];
+  const schemes = Object.entries(preparedSecurity)
+    .map(([, ps]) => ps.filter(s => usableScheme === s._key))
+    .reduce((prev, next) => prev.concat(next), []);
 
+  const scheme = schemes.shift();
   switch (scheme.type) {
     case 'http':
       if (scheme.scheme === 'basic') {
@@ -45,40 +85,24 @@ export default function prepareAuth(authKey: (number | string)[], operation: Ope
           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.'
-          );
-        }
-
         preparedAuth[scheme._key] = authKey[0];
       }
       break;
 
     case '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.'
-        );
-      }
-
       preparedAuth[scheme._key] = authKey[0];
       break;
 
     case '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' || scheme.in === 'cookie') {
         preparedAuth[scheme._key] = authKey[0];
       }
       break;
 
     default:
-      throw new Error(`Sorry, this API currently supports a scheme, ${scheme.type}, that we don't yet support.`);
+      throw new Error(
+        `Sorry, this API currently uses a security scheme, ${scheme.type}, which this library doesn't yet support.`
+      );
   }
 
   return preparedAuth;

package/src/core/prepareParams.ts

@@ -1,23 +1,30 @@
-import type { Operation } from 'oas';
-import type { ParameterObject, SchemaObject } from 'oas/@types/rmoas.types';
 import type { ReadStream } from 'fs';
+import type { Operation } from 'oas';
+import type { ParameterObject, SchemaObject } from 'oas/dist/rmoas.types';
 
-import lodashMerge from 'lodash.merge';
 import fs from 'fs/promises';
 import path from 'path';
 import stream from 'stream';
-import getStream from 'get-stream';
-import datauri from 'datauri/sync';
+
+import caseless from 'caseless';
 import DatauriParser from 'datauri/parser';
+import datauri from 'datauri/sync';
+import getStream from 'get-stream';
+import lodashMerge from 'lodash.merge';
+import removeUndefinedObjects from 'remove-undefined-objects';
+
 import getJSONSchemaDefaults from './getJSONSchemaDefaults';
 
+// These headers are normally only defined by the OpenAPI definition but we allow the user to
+// manually supply them in their `metadata` parameter if they wish.
+const specialHeaders = ['accept', 'authorization'];
+
 /**
  * Extract all available parameters from an operations Parameter Object into a digestable array
  * that we can use to apply to the request.
  *
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject}
  * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject}
- * @param parameters
  */
 function digestParameters(parameters: ParameterObject[]): Record<string, ParameterObject> {
   return parameters.reduce((prev, param) => {
@@ -65,8 +72,6 @@ function merge(src: any, target: any) {
  * Ingest a file path or readable stream into a common object that we can later use to process it
  * into a parameters object for making an API request.
  *
- * @param paramName
- * @param file
  */
 function processFile(
   paramName: string,
@@ -133,20 +138,49 @@ function processFile(
  * operation to see what's what and prepare any available parameters to be used in an API request
  * with `@readme/oas-to-har`.
  *
- * @param operation
- * @param body
- * @param metadata
  */
 export default async function prepareParams(operation: Operation, body?: unknown, metadata?: Record<string, unknown>) {
   let metadataIntersected = false;
   const digestedParameters = digestParameters(operation.getParameters());
-  const hasDigestedParams = !!Object.keys(digestedParameters).length;
-  const jsonSchema = operation.getParametersAsJsonSchema();
+  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."
-    );
+    let throwNoParamsError = true;
+
+    // If this operation doesn't have any parameters for us to transform to JSON Schema but they've
+    // sent us either an `Accept` or `Authorization` header (or both) we should let them do that.
+    // We should, however, only do this check for the `body` parameter as if they've sent this
+    // request both `body` and `metadata` we can reject it outright as the operation won't have any
+    // body data.
+    if (body !== undefined) {
+      if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+        if (Object.keys(body).length <= 2) {
+          const bodyParams = caseless(body);
+
+          if (specialHeaders.some(header => bodyParams.has(header))) {
+            throwNoParamsError = false;
+          }
+        }
+      }
+    }
+
+    if (throwNoParamsError) {
+      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."
+      );
+    }
   }
 
   const jsonSchemaDefaults = jsonSchema ? getJSONSchemaDefaults(jsonSchema) : {};
@@ -176,27 +210,44 @@ export default async function prepareParams(operation: Operation, body?: unknown
     } else if (typeof metadata === 'undefined') {
       // No metadata was explicitly provided so we need to analyze the body to determine if it's a
       // body or should be actually be treated as metadata.
-      if (!hasDigestedParams) {
-        // If no parameters were able to be digested it's because this operation has none so then
-        // we just have to assume that what the user supplied was for a body and not metadata. This
-        // might lead to unwanted false positives if the API definition isn't accurate but short of
-        // throwing an error (one that the user would have no control over resolving anyways) there
-        // 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;
-        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,
-          // then we should treat it as a metadata object and organize into parameters.
-          metadataIntersected = true;
-          metadata = merge(params.body, body) as Record<string, unknown>;
-          body = undefined;
-          /* eslint-enable no-param-reassign */
-        } else {
-          // For all other cases, we should just treat the supplied body as a body.
-          params.body = merge(params.body, body);
+      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, '');
+        }
+      });
+
+      // `Accept` and `Authorization` headers can't be defined as normal parameters but we should
+      // always allow the user to supply them if they wish.
+      specialHeaders.forEach(header => {
+        if (!headerParams.has(header)) {
+          headerParams.set(header, '');
+        }
+      });
+
+      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,
+        // then we should treat it as a metadata object and organize into parameters.
+        metadataIntersected = true;
+        metadata = merge(params.body, body) as Record<string, unknown>;
+        body = undefined;
+        /* eslint-enable no-param-reassign */
+      } else {
+        // For all other cases, we should just treat the supplied body as a body.
+        params.body = merge(params.body, body);
       }
     } else {
       // Body and metadata were both supplied.
@@ -268,7 +319,7 @@ export default async function prepareParams(operation: Operation, body?: unknown
   // Only spend time trying to organize metadata into parameters if we were able to digest
   // parameters out of the operation schema. If we couldn't digest anything, but metadata was
   // supplied then we wouldn't know how to send it in the request!
-  if (hasDigestedParams) {
+  if (typeof metadata !== 'undefined') {
     if (!('cookie' in params)) params.cookie = {};
     if (!('header' in params)) params.header = {};
     if (!('path' in params)) params.path = {};
@@ -276,8 +327,16 @@ 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];
+      let metadataHeaderParam;
+      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.
+          metadataHeaderParam = Object.keys(metadata).find(k => k.toLowerCase() === paramName.toLowerCase());
+          value = metadata[metadataHeaderParam];
+        }
       }
 
       if (value === undefined) {
@@ -295,8 +354,8 @@ export default async function prepareParams(operation: Operation, body?: unknown
           delete metadata[paramName];
           break;
         case 'header':
-          params.header[paramName] = value;
-          delete metadata[paramName];
+          params.header[paramName.toLowerCase()] = value;
+          delete metadata[metadataHeaderParam];
           break;
         case 'cookie':
           params.cookie[paramName] = value;
@@ -321,6 +380,18 @@ export default async function prepareParams(operation: Operation, body?: unknown
     if (!isEmpty(metadata)) {
       if (operation.isFormUrlEncoded()) {
         params.formData = merge(params.formData, metadata);
+      } else if (typeof metadata === 'object') {
+        // If the user supplied an `accept` or `authorization` header themselves we should allow it
+        // through. Normally these headers are automatically handled by `@readme/oas-to-har` but in
+        // the event that maybe the user wants to return XML for an API that normally returns JSON
+        // or specify a custom auth header (maybe we can't handle their auth case right) this is the
+        // only way with this library that they can do that.
+        specialHeaders.forEach(headerName => {
+          const headerParam = Object.keys(metadata).find(m => m.toLowerCase() === headerName);
+          if (headerParam) {
+            params.header[headerName] = metadata[headerParam] as string;
+          }
+        });
       } else {
         // Any other remaining unused metadata will be unused because we don't know where to place
         // it in the request.

package/src/fetcher.ts

@@ -1,11 +1,12 @@
-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';
-import yaml from 'js-yaml';
 import fs from 'fs';
 import path from 'path';
 
+import OpenAPIParser from '@readme/openapi-parser';
+import 'isomorphic-fetch';
+import yaml from 'js-yaml';
+
 export default class Fetcher {
   uri: string | OASDocument;