@readme/api-core 7.0.0-alpha.1

package/src/index.ts

@@ -0,0 +1,151 @@
+import type { Har } from 'har-format';
+import type Oas from 'oas';
+import type { Operation } from 'oas';
+import type { HttpMethods } from 'oas/dist/rmoas.types';
+
+import oasToHar from '@readme/oas-to-har';
+import fetchHar from 'fetch-har';
+
+import FetchError from './errors/fetchError';
+import getJSONSchemaDefaults from './lib/getJSONSchemaDefaults';
+import parseResponse from './lib/parseResponse';
+import prepareAuth from './lib/prepareAuth';
+import prepareParams from './lib/prepareParams';
+import prepareServer from './lib/prepareServer';
+
+export interface ConfigOptions {
+  /**
+   * Override the default `fetch` request timeout of 30 seconds. This number should be represented
+   * in milliseconds.
+   */
+  timeout?: number;
+}
+
+export interface FetchResponse<HTTPStatus, Data> {
+  data: Data;
+  headers: Headers;
+  res: Response;
+  status: HTTPStatus;
+}
+
+// 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 {
+  spec!: Oas;
+
+  private auth: (number | string)[] = [];
+
+  private server:
+    | false
+    | {
+        url: string;
+        variables?: Record<string, string | number>;
+      } = false;
+
+  private config: ConfigOptions = {};
+
+  private userAgent!: string;
+
+  constructor(spec?: Oas, userAgent?: string) {
+    if (spec) this.spec = spec;
+    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: string[] | number[]) {
+    this.auth = values;
+    return this;
+  }
+
+  setServer(url: string, variables: Record<string, string | number> = {}) {
+    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);
+  }
+
+  async fetchOperation<HTTPStatus extends number = number>(
+    operation: Operation,
+    body?: unknown,
+    metadata?: Record<string, unknown>,
+  ) {
+    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;
+        }
+      }
+
+      // @ts-expect-error `this.auth` typing is off. FIXME
+      const har = oasToHar(this.spec, 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,74 @@
+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';
+
+/**
+ * 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?: string | number,
+        ) => {
+          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/parseResponse.ts

@@ -0,0 +1,27 @@
+import { utils } from 'oas';
+
+const { matchesMimeType } = 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.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,110 @@
+/* eslint-disable no-underscore-dangle */
+import type { Operation } from 'oas';
+import type { KeyedSecuritySchemeObject } from 'oas/dist/rmoas.types';
+
+export default function prepareAuth(authKey: (number | string)[], operation: Operation) {
+  if (authKey.length === 0) {
+    return {};
+  }
+
+  const preparedAuth: Record<
+    string,
+    | string
+    | number
+    | {
+        pass: string | number;
+        user: string | number;
+      }
+  > = {};
+
+  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: authKey[0],
+      pass: authKey.length === 2 ? 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: authKey[0],
+          pass: authKey.length === 2 ? authKey[1] : '',
+        };
+      } else if (scheme.scheme === 'bearer') {
+        preparedAuth[scheme._key] = authKey[0];
+      }
+      break;
+
+    case 'oauth2':
+      preparedAuth[scheme._key] = authKey[0];
+      break;
+
+    case 'apiKey':
+      if (scheme.in === 'query' || scheme.in === 'header' || scheme.in === 'cookie') {
+        preparedAuth[scheme._key] = 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;
+}