@bfra.me/api-core 0.1.0

package/src/index.ts

@@ -0,0 +1,134 @@
+import type {ConfigOptions} from './types.js'
+import type {AuthForHAR, DataForHAR} from '@readme/oas-to-har/lib/types'
+import type {Har} from 'har-format'
+import type {Operation} from 'oas/operation'
+import type {HttpMethods, OASDocument} from 'oas/types'
+
+import oasToHar from '@readme/oas-to-har'
+import fetchHar from 'fetch-har'
+import Oas from 'oas'
+
+import FetchError from './errors/fetchError.js'
+import {parseResponse, prepareAuth, prepareParams, prepareServer} from './lib/index.js'
+
+export default class APICore {
+  spec!: Oas
+
+  private auth: (number | string)[] = []
+
+  private server:
+    | false
+    | {
+        url: string
+        variables?: Record<string, number | string>
+      } = false
+
+  private config: ConfigOptions = {}
+
+  private userAgent!: string
+
+  constructor(definition?: OASDocument | Record<string, unknown>, userAgent?: string) {
+    if (definition) this.spec = Oas.init(definition)
+    if (userAgent) this.userAgent = userAgent
+  }
+
+  setSpec(spec: Oas) {
+    this.spec = spec
+  }
+
+  setConfig(config: ConfigOptions) {
+    this.config = config
+    return this
+  }
+
+  setUserAgent(userAgent: string) {
+    this.userAgent = userAgent
+    return this
+  }
+
+  setAuth(...values: number[] | string[]) {
+    this.auth = values
+    return this
+  }
+
+  setServer(url: string, variables: Record<string, number | string> = {}) {
+    this.server = {url, variables}
+    return this
+  }
+
+  async fetch<HTTPStatus extends number = number>(
+    path: string,
+    method: HttpMethods,
+    body?: unknown,
+    metadata?: Record<string, unknown>,
+  ) {
+    const operation = this.spec.operation(path, method)
+
+    return this.fetchOperation<HTTPStatus>(operation, body, metadata)
+  }
+
+  /**
+   * Retrieve a HAR for a given HTTP request.
+   *
+   * @internal
+   */
+  getHARForRequest(operation: Operation, data: DataForHAR, auth: AuthForHAR) {
+    return oasToHar(this.spec, operation, data, auth)
+  }
+
+  async fetchOperation<HTTPStatus extends number = number>(
+    operation: Operation,
+    body?: unknown,
+    metadata?: Record<string, unknown>,
+  ) {
+    // eslint-disable-next-line @typescript-eslint/promise-function-async
+    return prepareParams(operation, body, metadata).then(params => {
+      const data = {...params}
+
+      // If `sdk.server()` has been issued data then we need to do some extra work to figure out
+      // how to use that supplied server, and also handle any server variables that were sent
+      // alongside it.
+      if (this.server) {
+        const preparedServer = prepareServer(this.spec, this.server.url, this.server.variables)
+        if (preparedServer) {
+          data.server = preparedServer
+        }
+      }
+
+      const har = this.getHARForRequest(operation, data, prepareAuth(this.auth, operation))
+
+      let timeoutSignal: NodeJS.Timeout
+      const init: RequestInit = {}
+      if (this.config.timeout) {
+        const controller = new AbortController()
+        timeoutSignal = setTimeout(() => controller.abort(), this.config.timeout)
+        init.signal = controller.signal
+      }
+
+      return fetchHar(har as Har, {
+        files: data.files || {},
+        init,
+        userAgent: this.userAgent,
+      })
+        .then(async (res: Response) => {
+          const parsed = await parseResponse<HTTPStatus>(res)
+
+          if (res.status >= 400 && res.status <= 599) {
+            throw new FetchError<typeof parsed.status, typeof parsed.data>(
+              parsed.status,
+              parsed.data,
+              parsed.headers,
+              parsed.res,
+            )
+          }
+
+          return parsed
+        })
+        .finally(() => {
+          if (this.config.timeout) {
+            clearTimeout(timeoutSignal)
+          }
+        })
+    })
+  }
+}

package/src/lib/getJSONSchemaDefaults.ts

@@ -0,0 +1,77 @@
+import type {SchemaWrapper} from 'oas/operation/get-parameters-as-json-schema'
+import type {SchemaObject} from 'oas/types'
+
+import traverse from 'json-schema-traverse'
+
+/**
+ * Run through a JSON Schema object and compose up an object containing default data for any schema
+ * property that is required and also has a defined default.
+ *
+ * Code partially adapted from the `json-schema-default` package but modified to only return
+ * defaults of required properties.
+ *
+ * @todo This is a good candidate to be moved into a core `oas` library method.
+ * @see {@link https://github.com/mdornseif/json-schema-default}
+ */
+export default function getJSONSchemaDefaults(jsonSchemas: SchemaWrapper[]) {
+  return jsonSchemas
+    .map(({type: payloadType, schema: jsonSchema}) => {
+      const defaults: Record<string, unknown> = {}
+      traverse(
+        jsonSchema,
+        (
+          schema: SchemaObject,
+          pointer: string,
+          _rootSchema: SchemaObject,
+          parentPointer?: string,
+          _parentKeyword?: string,
+          parentSchema?: SchemaObject,
+          indexProperty?: number | string,
+        ) => {
+          if (!pointer.startsWith('/properties/')) {
+            return
+          }
+
+          if (
+            Array.isArray(parentSchema?.required) &&
+            parentSchema?.required.includes(String(indexProperty))
+          ) {
+            if (schema.type === 'object' && indexProperty) {
+              defaults[indexProperty] = {}
+            }
+
+            let destination = defaults
+            if (parentPointer) {
+              // To map nested objects correct we need to pick apart the parent pointer.
+              parentPointer
+                .replace(/\/properties/g, '')
+                .split('/')
+                .forEach((subSchema: string) => {
+                  if (subSchema === '') {
+                    return
+                  }
+
+                  destination = (destination?.[subSchema] as Record<string, unknown>) || {}
+                })
+            }
+
+            if (schema.default !== undefined) {
+              if (indexProperty !== undefined) {
+                destination[indexProperty] = schema.default
+              }
+            }
+          }
+        },
+      )
+
+      if (!Object.keys(defaults).length) {
+        return {}
+      }
+
+      return {
+        // @todo should we filter out empty and undefined objects from here with `remove-undefined-objects`?
+        [payloadType]: defaults,
+      }
+    })
+    .reduce((prev, next) => Object.assign(prev, next))
+}

package/src/lib/index.ts

@@ -0,0 +1,7 @@
+import getJSONSchemaDefaults from './getJSONSchemaDefaults.js'
+import parseResponse from './parseResponse.js'
+import prepareAuth from './prepareAuth.js'
+import prepareParams from './prepareParams.js'
+import prepareServer from './prepareServer.js'
+
+export {getJSONSchemaDefaults, parseResponse, prepareAuth, prepareParams, prepareServer}

package/src/lib/parseResponse.ts

@@ -0,0 +1,28 @@
+import {matchesMimeType} from 'oas/utils'
+
+export default async function parseResponse<HTTPStatus extends number = number>(
+  response: Response,
+) {
+  const contentType = response.headers.get('Content-Type')
+  const isJSON =
+    contentType && (matchesMimeType.json(contentType) || matchesMimeType.wildcard(contentType))
+
+  const responseBody = await response.clone().text()
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let data: any = responseBody
+  if (isJSON) {
+    try {
+      data = JSON.parse(responseBody)
+    } catch (e) {
+      // If our JSON parsing failed then we can just return plaintext instead.
+    }
+  }
+
+  return {
+    data,
+    status: response.status as HTTPStatus,
+    headers: response.headers,
+    res: response,
+  }
+}

package/src/lib/prepareAuth.ts

@@ -0,0 +1,107 @@
+/* eslint-disable no-underscore-dangle */
+import type {AuthForHAR} from '@readme/oas-to-har/lib/types'
+import type {Operation} from 'oas/operation'
+import type {KeyedSecuritySchemeObject} from 'oas/types'
+
+export default function prepareAuth(authKey: (number | string)[], operation: Operation) {
+  if (authKey.length === 0) {
+    return {}
+  }
+
+  const preparedAuth: AuthForHAR = {}
+
+  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 {}
+  }
+
+  // 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.",
+    )
+  }
+
+  // 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() as KeyedSecuritySchemeObject
+    preparedAuth[scheme._key] = {
+      user: String(authKey[0]),
+      pass: authKey.length === 2 ? String(authKey[1]) : '',
+    }
+
+    return preparedAuth
+  }
+
+  // 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() as KeyedSecuritySchemeObject
+  switch (scheme.type) {
+    case 'http':
+      if (scheme.scheme === 'basic') {
+        preparedAuth[scheme._key] = {
+          user: String(authKey[0]),
+          pass: authKey.length === 2 ? String(authKey[1]) : '',
+        }
+      } else if (scheme.scheme === 'bearer') {
+        preparedAuth[scheme._key] = String(authKey[0])
+      }
+      break
+
+    case 'oauth2':
+      preparedAuth[scheme._key] = String(authKey[0])
+      break
+
+    case 'apiKey':
+      if (scheme.in === 'query' || scheme.in === 'header' || scheme.in === 'cookie') {
+        preparedAuth[scheme._key] = String(authKey[0])
+      }
+      break
+
+    default:
+      throw new Error(
+        `Sorry, this API currently uses a security scheme, ${scheme.type}, which this library doesn't yet support.`,
+      )
+  }
+
+  return preparedAuth
+}