@readme/api-core 7.0.0-alpha.1

package/src/lib/prepareParams.ts

@@ -0,0 +1,427 @@
+import type { ReadStream } from 'node:fs';
+import type { Operation } from 'oas';
+import type { ParameterObject, SchemaObject } from 'oas/dist/rmoas.types';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import stream from 'node: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
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isEmpty(obj: any) {
+  return [Object, Array].includes((obj || {}).constructor) && !Object.entries(obj || {}).length;
+}
+
+function isObject(thing: unknown) {
+  if (thing instanceof stream.Readable) {
+    return false;
+  }
+
+  return typeof thing === 'object' && thing !== null && !Array.isArray(thing);
+}
+
+function isPrimitive(obj: unknown) {
+  return obj === null || typeof obj === 'number' || typeof obj === 'string';
+}
+
+function merge(src: unknown, target: unknown) {
+  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 | undefined,
+  file: string | ReadStream,
+): Promise<{ base64?: string; buffer?: Buffer; filename: string; paramName?: string } | undefined> {
+  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: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    body?: any;
+    cookie?: Record<string, string | number | boolean>;
+    files?: Record<string, Buffer>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    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 as NonNullable<unknown>).filter(value => {
+        if (Object.keys(digestedParameters).includes(value)) {
+          return true;
+        } else if (headerParams.has(value)) {
+          return true;
+        }
+
+        return false;
+      }).length;
+
+      // 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.
+      if (intersection && intersection / Object.keys(body as NonNullable<unknown>).length > 0.25) {
+        /* eslint-disable no-param-reassign */
+        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;
+            }
+
+            if (fileMetadata.buffer && params?.files) {
+              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]) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let value: any;
+      let metadataHeaderParam;
+      if (typeof metadata === 'object' && !isEmpty(metadata)) {
+        if (paramName in metadata) {
+          value = metadata[paramName];
+          metadataHeaderParam = 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 as NonNullable<typeof params.path>)[paramName] = value;
+          if (metadata?.[paramName]) delete metadata[paramName];
+          break;
+        case 'query':
+          (params.query as NonNullable<typeof params.query>)[paramName] = value;
+          if (metadata?.[paramName]) delete metadata[paramName];
+          break;
+        case 'header':
+          (params.header as NonNullable<typeof params.header>)[paramName.toLowerCase()] = value;
+          if (metadataHeaderParam && metadata?.[metadataHeaderParam]) delete metadata[metadataHeaderParam];
+          break;
+        case 'cookie':
+          (params.cookie as NonNullable<typeof params.cookie>)[paramName] = value;
+          if (metadata?.[paramName]) 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 (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) {
+            // this if-statement below is a typeguard
+            if (typeof metadata === 'object') {
+              // this if-statement below is a typeguard
+              if (typeof params.header === 'object') {
+                params.header[headerName] = metadata[headerParam] as string;
+              }
+              // eslint-disable-next-line no-param-reassign
+              delete metadata[headerParam];
+            }
+          }
+        });
+      }
+
+      if (operation.isFormUrlEncoded()) {
+        params.formData = merge(params.formData, metadata);
+      } 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'] as const).forEach((type: keyof typeof params) => {
+    if (type in params && isEmpty(params[type])) {
+      delete params[type];
+    }
+  });
+
+  return params;
+}

package/src/lib/prepareServer.ts

@@ -0,0 +1,48 @@
+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/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "baseUrl": "./src",
+    "declaration": true,
+    "esModuleInterop": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "noImplicitAny": true,
+    "outDir": "dist/",
+    "strict": true
+  },
+  "include": ["./src/**/*"]
+}