@bfra.me/api-core 0.1.0

package/src/lib/prepareParams.ts

@@ -0,0 +1,439 @@
+import type {ReadStream} from 'node:fs'
+import type {Operation} from 'oas/operation'
+import type {ParameterObject, SchemaObject} from 'oas/types'
+
+import stream from 'node:stream'
+
+import caseless from 'caseless'
+// `get-stream` is included in our bundle, see `tsup.config.ts`
+// eslint-disable-next-line import/no-extraneous-dependencies
+import {getStreamAsBuffer} from 'get-stream'
+import lodashMerge from 'lodash.merge'
+import removeUndefinedObjects from 'remove-undefined-objects'
+
+import getJSONSchemaDefaults from './getJSONSchemaDefaults.js'
+
+// 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.
+ *
+ */
+async function processFile(
+  paramName: string | undefined,
+  file: ReadStream | string,
+): Promise<{base64?: string; buffer?: Buffer; filename: string; paramName?: string} | undefined> {
+  const fs = await import('node:fs')
+  const path = await import('node:path')
+  const {default: DatauriParser} = await import('datauri/parser.js')
+  const {default: datauri} = await import('datauri/sync.js')
+  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 getStreamAsBuffer(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, boolean | number | string>
+    files?: Record<string, Buffer>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    formData?: any
+    header?: Record<string, boolean | number | string>
+    path?: Record<string, boolean | number | string>
+    query?: Record<string, boolean | number | string>
+    server?: {
+      selected: number
+      variables: Record<string, number | string>
+    }
+  } = 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,52 @@
+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, number | string> = {},
+) {
+  let serverIdx: number | undefined
+  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 !== undefined) {
+    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/types.ts

@@ -0,0 +1,28 @@
+export type {FromSchema} from 'json-schema-to-ts'
+
+export interface ConfigOptions {
+  /**
+   * Override the default `fetch` request timeout of 30 seconds. This number should be represented
+   * in milliseconds.
+   */
+  timeout?: number
+}
+
+/**
+ * @see {@link 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 interface FetchResponse<HTTPStatus, Data> {
+  data: Data
+  headers: Headers
+  res: Response
+  status: HTTPStatus
+}

package/test-utils/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @api/test-utils
+
+## 0.1.0
+### Minor Changes
+
+
+
+- Add a fork of [`@readme/api-core`](https://github.com/readmeio/api/tree/main/packages/core) as `@bfra.me/api-core`:  
+  - Use `git subtree` to add `@readme/api-core` and `@api/test-utils` as forks
+  - Patch `@bfra.me/api-core` with readmeio/api#820, to fix issues bundling `@readme/api-core` for the browser
+  - Adjust forked packages to build, lint, and test within the `@bfra.me/works` monorepo (by [@marcusrbrown](https://github.com/marcusrbrown) with [#443](https://github.com/bfra-me/works/pull/443))