api 6.1.0 → 7.0.0-alpha.0

package/src/core/prepareParams.ts

@@ -1,410 +0,0 @@
-import type { ReadStream } from 'fs';
-import type { Operation } from 'oas';
-import type { ParameterObject, SchemaObject } from 'oas/dist/rmoas.types';
-
-import fs from 'fs';
-import path from 'path';
-import stream from 'stream';
-
-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}
- */
-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.");
-    } 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.`
-      );
-    }
-
-    return Object.assign(prev, { [param.name]: param });
-  }, {});
-}
-
-// https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_isempty
-function isEmpty(obj: any) {
-  return [Object, Array].includes((obj || {}).constructor) && !Object.entries(obj || {}).length;
-}
-
-function isObject(thing: any) {
-  if (thing instanceof stream.Readable) {
-    return false;
-  }
-
-  return typeof thing === 'object' && thing !== null && !Array.isArray(thing);
-}
-
-function isPrimitive(obj: any) {
-  return typeof obj === null || typeof obj === 'number' || typeof obj === 'string';
-}
-
-function merge(src: any, target: any) {
-  if (Array.isArray(target)) {
-    // @todo we need to add support for merging array defaults with array body/metadata arguments
-    return target;
-  } else if (!isObject(target)) {
-    return target;
-  }
-
-  return lodashMerge(src, target);
-}
-
-/**
- * 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.
- *
- */
-function processFile(
-  paramName: string,
-  file: string | ReadStream
-): Promise<{ base64: string; buffer: Buffer; filename: string; paramName: string }> {
-  if (typeof file === 'string') {
-    // In order to support relative pathed files, we need to attempt to resolve them.
-    const resolvedFile = path.resolve(file);
-
-    return new Promise((resolve, reject) => {
-      fs.stat(resolvedFile, async err => {
-        if (err) {
-          if (err.code === 'ENOENT') {
-            // It's less than ideal for us to handle files that don't exist like this but because
-            // `file` is a string it might actually be the full text contents of the file and not
-            // actually a path.
-            //
-            // We also can't really regex to see if `file` *looks*` like a path because one should be
-            // able to pass in a relative `owlbert.png` (instead of `./owlbert.png`) and though that
-            // doesn't *look* like a path, it is one that should still work.
-            return resolve(undefined);
-          }
-
-          return reject(err);
-        }
-
-        const fileMetadata = await datauri(resolvedFile);
-        const payloadFilename = encodeURIComponent(path.basename(resolvedFile));
-
-        return resolve({
-          paramName,
-          base64: fileMetadata.content.replace(';base64', `;name=${payloadFilename};base64`),
-          filename: payloadFilename,
-          buffer: fileMetadata.buffer,
-        });
-      });
-    });
-  } else if (file instanceof stream.Readable) {
-    return getStream.buffer(file).then(buffer => {
-      const filePath = file.path as string;
-      const parser = new DatauriParser();
-      const base64 = parser.format(filePath, buffer).content;
-      const payloadFilename = encodeURIComponent(path.basename(filePath));
-
-      return {
-        paramName,
-        base64: base64.replace(';base64', `;name=${payloadFilename};base64`),
-        filename: payloadFilename,
-        buffer,
-      };
-    });
-  }
-
-  return Promise.reject(
-    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.'
-    )
-  );
-}
-
-/**
- * With potentially supplied body and/or metadata we need to run through them against a given API
- * operation to see what's what and prepare any available parameters to be used in an API request
- * with `@readme/oas-to-har`.
- *
- */
-export default async function prepareParams(operation: Operation, body?: unknown, metadata?: Record<string, unknown>) {
-  let metadataIntersected = false;
-  const digestedParameters = digestParameters(operation.getParameters());
-  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)) {
-    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) : {};
-
-  const params: {
-    body?: any;
-    cookie?: Record<string, string | number | boolean>;
-    files?: Record<string, Buffer>;
-    formData?: any;
-    header?: Record<string, string | number | boolean>;
-    path?: Record<string, string | number | boolean>;
-    query?: Record<string, string | number | boolean>;
-    server?: {
-      selected: number;
-      variables: Record<string, string | number>;
-    };
-  } = jsonSchemaDefaults;
-
-  // If a body argument was supplied we need to do a bit of work to see if it's actually a body
-  // argument or metadata because the library lets you supply either a body, metadata, or body with
-  // metadata.
-  if (typeof body !== 'undefined') {
-    if (Array.isArray(body) || isPrimitive(body)) {
-      // If the body param is an array or a primitive then we know it's absolutely a body because
-      // metadata can only ever be undefined or an object.
-      params.body = merge(params.body, body);
-    } 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.
-      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.
-      params.body = merge(params.body, body);
-    }
-  }
-
-  if (!operation.hasRequestBody()) {
-    // If this operation doesn't have any documented request body then we shouldn't be sending
-    // anything.
-    delete params.body;
-  } else {
-    if (!('body' in params)) params.body = {};
-
-    // We need to retrieve the request body for this operation to search for any `binary` format
-    // data that the user wants to send so we know what we need to prepare for the final API
-    // request.
-    const payloadJsonSchema = jsonSchema.find(js => js.type === 'body');
-    if (payloadJsonSchema) {
-      if (!params.files) params.files = {};
-
-      const conversions = [];
-
-      // @todo add support for `type: array`, `oneOf` and `anyOf`
-      if (payloadJsonSchema.schema?.properties) {
-        Object.entries(payloadJsonSchema.schema?.properties)
-          .filter(([, schema]: [string, SchemaObject]) => schema?.format === 'binary')
-          .filter(([prop]) => Object.keys(params.body).includes(prop))
-          .forEach(([prop]) => {
-            conversions.push(processFile(prop, params.body[prop]));
-          });
-      } else if (payloadJsonSchema.schema?.type === 'string') {
-        if (payloadJsonSchema.schema?.format === 'binary') {
-          conversions.push(processFile(undefined, params.body));
-        }
-      }
-
-      await Promise.all(conversions)
-        .then(fileMetadata => fileMetadata.filter(Boolean))
-        .then(fm => {
-          fm.forEach(fileMetadata => {
-            if (!fileMetadata) {
-              // If we don't have any metadata here it's because the file we have is likely
-              // the full string content of the file so since we don't have any filenames to
-              // work with we shouldn't do any additional handling to the `body` or `files`
-              // parameters.
-              return;
-            }
-
-            if (fileMetadata.paramName) {
-              params.body[fileMetadata.paramName] = fileMetadata.base64;
-            } else {
-              params.body = fileMetadata.base64;
-            }
-
-            params.files[fileMetadata.filename] = fileMetadata.buffer;
-          });
-        });
-    }
-  }
-
-  // Form data should be placed within `formData` instead of `body` for it to properly get picked
-  // up by `fetch-har`.
-  if (operation.isFormUrlEncoded()) {
-    params.formData = merge(params.formData, params.body);
-    delete params.body;
-  }
-
-  // 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 (typeof metadata !== 'undefined') {
-    if (!('cookie' in params)) params.cookie = {};
-    if (!('header' in params)) params.header = {};
-    if (!('path' in params)) params.path = {};
-    if (!('query' in params)) params.query = {};
-
-    Object.entries(digestedParameters).forEach(([paramName, param]) => {
-      let value: any;
-      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) {
-        return;
-      }
-
-      /* eslint-disable no-param-reassign */
-      switch (param.in) {
-        case 'path':
-          params.path[paramName] = value;
-          delete metadata[paramName];
-          break;
-        case 'query':
-          params.query[paramName] = value;
-          delete metadata[paramName];
-          break;
-        case 'header':
-          params.header[paramName.toLowerCase()] = value;
-          delete metadata[metadataHeaderParam];
-          break;
-        case 'cookie':
-          params.cookie[paramName] = value;
-          delete metadata[paramName];
-          break;
-        default: // no-op
-      }
-      /* eslint-enable no-param-reassign */
-
-      // Because a user might have sent just a metadata object, we want to make sure that we filter
-      // out anything that they sent that is a parameter from also being sent as part of a form
-      // data payload for `x-www-form-urlencoded` requests.
-      if (metadataIntersected && operation.isFormUrlEncoded()) {
-        if (paramName in params.formData) {
-          delete params.formData[paramName];
-        }
-      }
-    });
-
-    // If there's any leftover metadata that hasn't been moved into form data for this request we
-    // need to move it or else it'll get tossed.
-    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.
-      }
-    }
-  }
-
-  ['body', 'cookie', 'files', 'formData', 'header', 'path', 'query'].forEach((type: keyof typeof params) => {
-    if (type in params && isEmpty(params[type])) {
-      delete params[type];
-    }
-  });
-
-  return params;
-}

package/src/core/prepareServer.ts

@@ -1,48 +0,0 @@
-import type Oas from 'oas';
-
-function stripTrailingSlash(url: string) {
-  if (url[url.length - 1] === '/') {
-    return url.slice(0, -1);
-  }
-
-  return url;
-}
-
-/**
- * With an SDK server config and an instance of OAS we should extract and prepare the server and
- * any server variables to be supplied to `@readme/oas-to-har`.
- *
- */
-export default function prepareServer(spec: Oas, url: string, variables: Record<string, string | number> = {}) {
-  let serverIdx;
-  const sanitizedUrl = stripTrailingSlash(url);
-  (spec.api.servers || []).forEach((server, i) => {
-    if (server.url === sanitizedUrl) {
-      serverIdx = i;
-    }
-  });
-
-  // If we were able to find the passed in server in the OAS servers, we should use that! If we
-  // couldn't and server variables were passed in we should try our best to handle that, otherwise
-  // we should ignore the passed in server and use whever the default from the OAS is.
-  if (serverIdx) {
-    return {
-      selected: serverIdx,
-      variables,
-    };
-  } else if (Object.keys(variables).length) {
-    // @todo we should run `oas.replaceUrl(url)` and pass that unto `@readme/oas-to-har`
-  } else {
-    const server = spec.splitVariables(url);
-    if (server) {
-      return {
-        selected: server.selected,
-        variables: server.variables,
-      };
-    }
-
-    // @todo we should pass `url` directly into `@readme/oas-to-har` as the base URL
-  }
-
-  return false;
-}

package/src/index.ts

@@ -1,203 +0,0 @@
-import type { ConfigOptions } from './core';
-import type { Operation } from 'oas';
-import type { OASDocument } from 'oas/dist/rmoas.types';
-
-import Oas from 'oas';
-
-import Cache from './cache';
-import APICore from './core';
-import { PACKAGE_NAME, PACKAGE_VERSION } from './packageInfo';
-
-interface SDKOptions {
-  cacheDir?: string;
-}
-
-class Sdk {
-  uri: string | OASDocument;
-
-  userAgent: string;
-
-  cacheDir: string | false;
-
-  constructor(uri: string | OASDocument, opts: SDKOptions = {}) {
-    this.uri = uri;
-    this.userAgent = `${PACKAGE_NAME} (node)/${PACKAGE_VERSION}`;
-
-    this.cacheDir = opts.cacheDir ? opts.cacheDir : false;
-  }
-
-  load() {
-    const cache = new Cache(this.uri, this.cacheDir);
-    const userAgent = this.userAgent;
-
-    const core = new APICore();
-    core.setUserAgent(userAgent);
-
-    let isLoaded = false;
-    let isCached = cache.isCached();
-    let sdk = {};
-
-    /**
-     * Create dynamic accessors for every operation with a defined operation ID. If an operation
-     * does not have an operation ID it can be accessed by its `.method('/path')` accessor instead.
-     *
-     */
-    function loadOperations(spec: Oas) {
-      return Object.entries(spec.getPaths())
-        .map(([, operations]) => Object.values(operations))
-        .reduce((prev, next) => prev.concat(next), [])
-        .reduce((prev, next) => {
-          // `getOperationId()` creates dynamic operation IDs when one isn't available but we need
-          // to know here if we actually have one present or not. The `camelCase` option here also
-          // cleans up any `operationId` that we might have into something that can be used as a
-          // valid JS method.
-          const originalOperationId = next.getOperationId();
-          const operationId = next.getOperationId({ camelCase: true });
-
-          const op = {
-            [operationId]: ((operation: Operation, ...args: unknown[]) => {
-              return core.fetchOperation(operation, ...args);
-            }).bind(null, next),
-          };
-
-          if (operationId !== originalOperationId) {
-            // If we cleaned up their operation ID into a friendly method accessor (`findPetById`
-            // versus `find pet by id`) we should still let them use the non-friendly version if
-            // they want.
-            //
-            // This work is to maintain backwards compatibility with `api@4` and does not exist
-            // within our code generated SDKs -- those only allow the cleaner camelCase
-            // `operationId` to be used.
-            op[originalOperationId] = ((operation: Operation, ...args: unknown[]) => {
-              return core.fetchOperation(operation, ...args);
-            }).bind(null, next);
-          }
-
-          return Object.assign(prev, op);
-        }, {});
-    }
-
-    async function loadFromCache() {
-      let cachedSpec;
-      if (isCached) {
-        cachedSpec = await cache.get();
-      } else {
-        cachedSpec = await cache.load();
-        isCached = true;
-      }
-
-      const spec = new Oas(cachedSpec);
-
-      core.setSpec(spec);
-
-      sdk = Object.assign(sdk, loadOperations(spec));
-      isLoaded = true;
-    }
-
-    const sdkProxy = {
-      // @give this a better type than any
-      get(target: any, method: string) {
-        // Since auth returns a self-proxy, we **do not** want it to fall through into the async
-        // function below as when that'll happen, instead of returning a self-proxy, it'll end up
-        // returning a Promise. When that happens, chaining `sdk.auth().operationId()` will fail.
-        if (['auth', 'config'].includes(method)) {
-          // @todo split this up so we have better types for `auth` and `config`
-          return function authAndConfigHandler(...args: any) {
-            return target[method].apply(this, args);
-          };
-        }
-
-        return async function accessorHandler(...args: unknown[]) {
-          if (!(method in target)) {
-            // If this method doesn't exist on the proxy, have we loaded the SDK? If we have, then
-            // this method isn't valid.
-            if (isLoaded) {
-              throw new Error(`Sorry, \`${method}\` does not appear to be a valid operation on this API.`);
-            }
-
-            await loadFromCache();
-
-            // If after loading the SDK and this method still doesn't exist, then it's not real!
-            if (!(method in sdk)) {
-              throw new Error(`Sorry, \`${method}\` does not appear to be a valid operation on this API.`);
-            }
-
-            // @todo give sdk a better type
-            return (sdk as any)[method].apply(this, args);
-          }
-
-          return target[method].apply(this, args);
-        };
-      },
-    };
-
-    sdk = {
-      /**
-       * If the API you're using requires authentication you can supply the required credentials
-       * through this method and the library will magically determine how they should be used
-       * within your API request.
-       *
-       * With the exception of OpenID and MutualTLS, it supports all forms of authentication
-       * supported by the OpenAPI specification.
-       *
-       * @example <caption>HTTP Basic auth</caption>
-       * sdk.auth('username', 'password');
-       *
-       * @example <caption>Bearer tokens (HTTP or OAuth 2)</caption>
-       * sdk.auth('myBearerToken');
-       *
-       * @example <caption>API Keys</caption>
-       * sdk.auth('myApiKey');
-       *
-       * @see {@link https://spec.openapis.org/oas/v3.0.3#fixed-fields-22}
-       * @see {@link https://spec.openapis.org/oas/v3.1.0#fixed-fields-22}
-       * @param values Your auth credentials for the API. Can specify up to two strings or numbers.
-       */
-      auth: (...values: string[] | number[]) => {
-        core.setAuth(...values);
-      },
-
-      /**
-       * Optionally configure various options that the SDK allows.
-       *
-       * @param config Object of supported SDK options and toggles.
-       * @param config.timeout Override the default `fetch` request timeout of 30 seconds (30000ms).
-       */
-      config: (config: ConfigOptions) => {
-        core.setConfig(config);
-      },
-
-      /**
-       * If the API you're using offers alternate server URLs, and server variables, you can tell
-       * the SDK which one to use with this method. To use it you can supply either one of the
-       * server URLs that are contained within the OpenAPI definition (along with any server
-       * variables), or you can pass it a fully qualified URL to use (that may or may not exist
-       * within the OpenAPI definition).
-       *
-       * @example <caption>Server URL with server variables</caption>
-       * sdk.server('https://{region}.api.example.com/{basePath}', {
-       *   name: 'eu',
-       *   basePath: 'v14',
-       * });
-       *
-       * @example <caption>Fully qualified server URL</caption>
-       * sdk.server('https://eu.api.example.com/v14');
-       *
-       * @param url Server URL
-       * @param variables An object of variables to replace into the server URL.
-       */
-      server: (url: string, variables = {}) => {
-        core.setServer(url, variables);
-      },
-    };
-
-    return new Proxy(sdk, sdkProxy);
-  }
-}
-
-// Why `export` vs `export default`? If we leave this as `export` then TS will transpile it into
-// a `module.exports` export so that when folks load this they don't need to load it as
-// `require('api').default`.
-export = (uri: string | OASDocument, opts: SDKOptions = {}) => {
-  return new Sdk(uri, opts).load();
-};

package/src/typings.d.ts

@@ -1,2 +0,0 @@
-// These libraries don't have any types so we need to let TS know so we can use them.
-declare module 'fetch-har';