@rossum/api-client 0.1.21 → 0.1.23

package/src/utils/keyConvertor.ts

@@ -0,0 +1,147 @@
+// Too difficult to type properly.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  camelCase,
+  includes,
+  isArray,
+  isPlainObject,
+  isString,
+  mapKeys as _mapKeys,
+  mapValues,
+  omitBy,
+  pickBy,
+  snakeCase,
+  upperFirst as _upperFirst,
+} from 'lodash';
+
+// https://stackoverflow.com/questions/60269936/typescript-convert-generic-object-from-snake-to-camel-case
+export type SnakeToCamel<S extends string> =
+  S extends `${infer T}_${infer U}_${infer V}`
+    ? `${T}${Capitalize<U>}${Capitalize<SnakeToCamel<V>>}`
+    : S extends `${infer T}_${infer U}`
+    ? `${T}${Capitalize<SnakeToCamel<U>>}`
+    : S;
+
+export type CamelToSnake<S extends string> =
+  S extends `${infer T}${infer U}${infer V}`
+    ? `${T extends Capitalize<T>
+        ? '_'
+        : ''}${Lowercase<T>}${U extends Capitalize<U>
+        ? '_'
+        : ''}${Lowercase<U>}${CamelToSnake<V>}`
+    : S extends `${infer T}${infer U}`
+    ? `${T extends Capitalize<T> ? '_' : ''}${Lowercase<T>}${CamelToSnake<U>}`
+    : S;
+
+export const snakeToCamel = <T extends string>(s: T): SnakeToCamel<T> =>
+  camelCase(s) as SnakeToCamel<T>;
+
+/** @public */
+export const camelToSnake = <T extends string>(s: T): CamelToSnake<T> =>
+  snakeCase(s) as CamelToSnake<T>;
+
+type SnakeToCamelObject<T> = T extends object
+  ? {
+      [K in keyof T as SnakeToCamel<K & string>]: SnakeToCamelObject<T[K]>;
+    }
+  : T;
+
+type CamelToSnakeObject<T> = T extends object
+  ? { [K in keyof T as CamelToSnake<K & string>]: CamelToSnakeObject<T[K]> }
+  : T;
+
+const caseArrayOrObject = (
+  target: any,
+  {
+    asObject,
+    asArray,
+    asString = x => x,
+  }: {
+    asObject: (_obj: Record<string, any>) => object;
+    asArray: (_arr: Array<any>) => Array<any>;
+    asString?: (_str: string) => string;
+  }
+) =>
+  isPlainObject(target)
+    ? asObject(target)
+    : isArray(target)
+    ? asArray(target)
+    : isString(target)
+    ? asString(target)
+    : target;
+
+// possible overloads, last one is just for backwards compatibility
+type KeyConvertor = {
+  <InputType>(
+    fn: <T extends string>(_key: T) => SnakeToCamel<T>,
+    excludeParentKeys?: string[]
+  ): (target: InputType) => SnakeToCamelObject<InputType>;
+  <InputType>(
+    fn: <T extends string>(_key: T) => CamelToSnake<T>,
+    excludeParentKeys?: string[]
+  ): (target: InputType) => CamelToSnakeObject<InputType>;
+  <InputType>(fn: (_key: string) => string, excludeParentKeys?: string[]): (
+    target: InputType
+  ) => any;
+};
+
+export const convertKeys: KeyConvertor =
+  (fn: any, excludeParentKeys: string[] = []) =>
+  (target: any): any =>
+    caseArrayOrObject(target, {
+      asObject: object =>
+        Object.keys(object).reduce(
+          (acc, key) => ({
+            ...acc,
+            [fn(key)]: excludeParentKeys.includes(key)
+              ? object[key]
+              : convertKeys(fn, excludeParentKeys)(object[key]),
+          }),
+          {}
+        ),
+      asArray: array => array.map(convertKeys(fn, excludeParentKeys)),
+    });
+
+type Camelify<T> = T extends object
+  ? {
+      [K in keyof T as SnakeToCamel<K & string>]: T[K];
+    }
+  : T;
+
+type Snakify<T> = T extends object
+  ? { [K in keyof T as CamelToSnake<K & string>]: T[K] }
+  : T;
+
+type KeyMapper = {
+  <InputType>(fn: <T extends string>(_key: T) => SnakeToCamel<T>): (
+    target: InputType
+  ) => Camelify<InputType>;
+  <InputType>(fn: <T extends string>(_key: T) => CamelToSnake<T>): (
+    target: InputType
+  ) => Snakify<InputType>;
+};
+
+export const convertStringValues =
+  (fn: (_key: string) => string, exclude: string[] = []) =>
+  (target: any): any =>
+    caseArrayOrObject(target, {
+      asObject: object => {
+        const toConvert = omitBy(object, (_, key) => includes(exclude, key));
+        const excluded = pickBy(object, (_, key) => includes(exclude, key));
+        const converted = mapValues(toConvert, convertStringValues(fn));
+
+        return { ...converted, ...excluded };
+      },
+      asArray: array => array.map(convertStringValues(fn)),
+      asString: fn,
+    });
+
+// https://stackoverflow.com/a/70831818
+export type Split<S extends string, D extends string> = string extends S
+  ? string[]
+  : S extends ''
+  ? []
+  : S extends `${infer T}${D}${infer U}`
+  ? [T, ...Split<U, D>]
+  : [S];

package/src/utils/listQuery.schema.ts

@@ -0,0 +1,7 @@
+// Generated by ts-to-zod
+import { z } from 'zod';
+
+export const paginationQuerySchema = z.object({
+  pageSize: z.number().optional(),
+  page: z.number().optional(),
+});

package/src/utils/listQuery.ts

@@ -0,0 +1,4 @@
+export type PaginationQuery = {
+  pageSize?: number;
+  page?: number;
+};

package/src/utils/listResponse.ts

@@ -0,0 +1,33 @@
+import { z, ZodTypeAny } from 'zod';
+import { PaginationResponse } from './pagination';
+import { paginationResponseSchema } from './pagination.schema';
+
+export const listResponse = <T extends ZodTypeAny>(itemSchema: T) => {
+  return z.object({
+    pagination: paginationResponseSchema,
+    results: z.array(itemSchema),
+  });
+};
+
+/**
+ * @noSchema
+ */
+export type ListResponse<T> = {
+  pagination: PaginationResponse;
+  results: T[];
+};
+
+export const unpaginatedListResponse = <T extends ZodTypeAny>(
+  itemSchema: T
+) => {
+  return z.object({
+    results: z.array(itemSchema),
+  });
+};
+
+/**
+ * @noSchema
+ */
+export type UnpaginatedListResponse<T> = {
+  results: T[];
+};

package/src/utils/pagination.schema.ts

@@ -0,0 +1,9 @@
+// Generated by ts-to-zod
+import { z } from 'zod';
+
+export const paginationResponseSchema = z.object({
+  next: z.string().nullable(),
+  previous: z.string().nullable(),
+  total: z.number(),
+  totalPages: z.number(),
+});

package/src/utils/pagination.ts

@@ -0,0 +1,6 @@
+export type PaginationResponse = {
+  next: string | null;
+  previous: string | null;
+  total: number;
+  totalPages: number;
+};

package/src/utils/request.ts

@@ -0,0 +1,79 @@
+import axios, { AxiosRequestConfig, AxiosResponse } from 'axios';
+import * as E from 'fp-ts/lib/Either';
+import { pipe } from 'fp-ts/lib/function';
+import * as TE from 'fp-ts/lib/TaskEither';
+import { ElisClientError, HttpError } from '../errors';
+import { RequestError } from '../errors/requestError';
+import { ElisClientConfig } from './client';
+import { buildAxiosConfig, ElisRequestConfig } from './requestConfig';
+import { asDecoded } from './requestResponse';
+
+const axiosRequest = (config: AxiosRequestConfig) =>
+  TE.tryCatch<ElisClientError, AxiosResponse<unknown>>(
+    () => axios.request(config),
+    (error: unknown) => {
+      if (axios.isAxiosError(error)) {
+        // We know that axios config always has URL.
+        const url = config.url!;
+        return error.response
+          ? new HttpError({
+              endpoint: url,
+              method: config.method,
+              statusCode: error.response.status,
+              data: error.response.data,
+              headers: error.response.headers,
+            })
+          : new RequestError({
+              endpoint: url,
+              message: `${error.message}\ncode:${error.code}`,
+            });
+      }
+      // This is absolutely not supposed to happen.
+      return new RequestError({
+        endpoint: '',
+        message: 'Invalid request error',
+      });
+    }
+  );
+
+export const request = <R, Q, P>(
+  clientConfig: ElisClientConfig,
+  requestConfig: ElisRequestConfig<R, Q, P>
+) =>
+  new Promise<R>((resolve, reject) =>
+    pipe(
+      buildAxiosConfig(clientConfig, requestConfig),
+      TE.fromEither,
+      TE.chain(axiosRequest),
+      TE.map(x => x.data),
+      TE.chainEitherK(asDecoded(clientConfig, requestConfig))
+    )().then(
+      E.fold(
+        e => reject(e),
+        d => resolve(d)
+      )
+    )
+  );
+
+export const fullRequest = <R, Q, P>(
+  clientConfig: ElisClientConfig,
+  requestConfig: ElisRequestConfig<R, Q, P>
+) =>
+  new Promise<AxiosResponse<R>>((resolve, reject) =>
+    pipe(
+      buildAxiosConfig(clientConfig, requestConfig),
+      TE.fromEither,
+      TE.chain(axiosRequest),
+      TE.chainEitherK(response =>
+        pipe(
+          asDecoded(clientConfig, requestConfig)(response.data),
+          E.map(data => ({ ...response, data }))
+        )
+      )
+    )().then(
+      E.fold(
+        e => reject(e),
+        d => resolve(d)
+      )
+    )
+  );

package/src/utils/requestConfig.ts

@@ -0,0 +1,280 @@
+import { AxiosRequestConfig, Method } from 'axios';
+import * as E from 'fp-ts/lib/Either';
+import { pipe } from 'fp-ts/lib/function';
+import { defaults, identity } from 'lodash';
+import { merge } from 'lodash/fp';
+import { ZodType, ZodTypeDef } from 'zod';
+import { ElisClientError } from '../errors';
+import { asPayloadEncoder, asQueryEncoder, toSnakeCase } from '../utils';
+import { ElisClientConfig, ElisContentType } from './client';
+import { payloadToFormData } from './requestUtils';
+import { encodeObjectToQuery } from './urlUtils';
+
+type ElisRequestConfigBase = {
+  endpoint: string;
+  method?: Method;
+  authorize?: boolean;
+  withRossumRequestOrigin?: boolean;
+  headers?: Record<string, string>;
+  contentType?: ElisContentType;
+  signal?: AbortSignal;
+};
+
+/**
+ * @noSchema
+ */
+type WithQuery<Q> = [Q] extends [never]
+  ? {
+      query?: never;
+      querySchema?: never;
+    }
+  : {
+      query: Q;
+      querySchema: ZodType<Q, ZodTypeDef, unknown>;
+    };
+
+/**
+ * @noSchema
+ */
+type WithPayload<P> = [P] extends [never]
+  ? {
+      payload?: never;
+      payloadSchema?: never;
+    }
+  : {
+      payload: P;
+      payloadSchema: ZodType<P, ZodTypeDef, unknown>;
+    };
+
+// To fix strict null checks.
+/**
+ * @noSchema
+ */
+type DeepPartial<T> = T extends object
+  ? {
+      [P in keyof T]?: DeepPartial<T[P]>;
+    }
+  : T;
+
+// add content type config
+/**
+ * @noSchema
+ */
+type WithResponse<R> =
+  // always require responseDecoder for 'json' responses - worst case scenario identity
+  | {
+      responseType: 'json';
+      responseSchema: ZodType<R, ZodTypeDef, unknown>;
+    }
+  // responseType defaults to json, so require decoder too
+  | {
+      responseType?: undefined;
+      responseSchema: ZodType<R, ZodTypeDef, unknown>;
+    }
+  // don't pass decoder for other responseTypes
+  | {
+      responseType: 'blob' | 'document' | 'text' | 'arraybuffer';
+      responseSchema?: never;
+    };
+
+/**
+ * @noSchema
+ */
+export type ElisRequestConfig<R, Q, P> = ElisRequestConfigBase &
+  WithQuery<Q> &
+  WithPayload<P> &
+  WithResponse<R>;
+
+export const withRequestConfigDefaults = <R, Q, P>(
+  requestConfig: ElisRequestConfig<R, Q, P>
+): ElisRequestConfig<R, Q, P> =>
+  defaults(requestConfig, {
+    method: requestConfig.method ?? 'GET',
+    responseType: requestConfig.responseType ?? 'json',
+    authorize: requestConfig.authorize ?? true,
+    withRossumRequestOrigin: requestConfig.withRossumRequestOrigin ?? true,
+  });
+
+export const asAxiosConfig =
+  <R, Q, P>(clientConfig: ElisClientConfig) =>
+  (
+    requestConfig: ElisRequestConfig<R, Q, P>
+  ): E.Either<ElisClientError, AxiosRequestConfig> => {
+    const { baseUrl } = clientConfig;
+    const { endpoint, method, headers, responseType, signal } = requestConfig;
+
+    return E.right({
+      baseURL: endpoint.startsWith('/api/') ? new URL(baseUrl).origin : baseUrl,
+      url: endpoint,
+      method,
+      headers,
+      responseType,
+      signal,
+    });
+  };
+
+export const withResponseHeaders =
+  <R, Q, P>(
+    _clientConfig: ElisClientConfig,
+    _requestConfig: ElisRequestConfig<R, Q, P>
+  ) =>
+  (
+    axiosConfig: AxiosRequestConfig
+  ): E.Either<ElisClientError, AxiosRequestConfig> => {
+    const { responseType } = axiosConfig;
+
+    return E.right(
+      pipe(
+        axiosConfig,
+        merge(
+          responseType === 'json'
+            ? { headers: { Accept: 'application/json' } }
+            : undefined
+        )
+      )
+    );
+  };
+
+export const withContentTypeHeaders =
+  <R, Q, P>(
+    _clientConfig: ElisClientConfig,
+    requestConfig: ElisRequestConfig<R, Q, P>
+  ) =>
+  (
+    axiosConfig: AxiosRequestConfig
+  ): E.Either<ElisClientError, AxiosRequestConfig> => {
+    const { contentType, payload } = requestConfig;
+
+    return E.right(
+      pipe(
+        axiosConfig,
+        merge(
+          typeof payload !== 'undefined'
+            ? { headers: { 'Content-Type': contentType ?? 'application/json' } }
+            : undefined
+        )
+      )
+    );
+  };
+
+export const withAuthorizationHeader =
+  <R, Q, P>(
+    clientConfig: ElisClientConfig,
+    requestConfig: ElisRequestConfig<R, Q, P>
+  ) =>
+  (
+    axiosConfig: AxiosRequestConfig
+  ): E.Either<ElisClientError, AxiosRequestConfig> => {
+    const { authorize } = requestConfig;
+    const { getAuthToken } = clientConfig;
+    return E.right(
+      merge(axiosConfig, {
+        headers: authorize
+          ? { Authorization: `Token ${getAuthToken()}` }
+          : undefined,
+      })
+    );
+  };
+
+export const withTrackingHeader =
+  <R, Q, P>(
+    _clientConfig: ElisClientConfig,
+    requestConfig: ElisRequestConfig<R, Q, P>
+  ) =>
+  (
+    axiosConfig: AxiosRequestConfig
+  ): E.Either<ElisClientError, AxiosRequestConfig> => {
+    const { withRossumRequestOrigin } = requestConfig;
+    return E.right(
+      merge(axiosConfig, {
+        // headers: withRossumRequestOrigin ? rossumTrackingOrigin : undefined,
+      })
+    );
+  };
+
+export const withAdditionalHeaders =
+  <R, Q, P>(
+    clientConfig: ElisClientConfig,
+    _requestConfig: ElisRequestConfig<R, Q, P>
+  ) =>
+  (
+    axiosConfig: AxiosRequestConfig
+  ): E.Either<ElisClientError, AxiosRequestConfig> => {
+    return E.right(
+      merge(axiosConfig, {
+        headers: clientConfig.additionalHeaders,
+      })
+    );
+  };
+
+export const withParams =
+  <R, Q, P>(
+    clientConfig: ElisClientConfig,
+    requestConfig: ElisRequestConfig<R, Q, P>
+  ) =>
+  (
+    axiosConfig: AxiosRequestConfig
+  ): E.Either<ElisClientError, AxiosRequestConfig> => {
+    const { query, querySchema } = requestConfig;
+
+    if (query && querySchema) {
+      const keyTransform =
+        clientConfig.convertKeys === 'none' ? identity : toSnakeCase;
+      return E.right(
+        merge(axiosConfig, {
+          params: asQueryEncoder(querySchema, keyTransform).encode(query),
+          paramsSerializer: encodeObjectToQuery,
+        })
+      );
+    }
+
+    return E.right(axiosConfig);
+  };
+
+export const withData =
+  <R, Q, P>(
+    clientConfig: ElisClientConfig,
+    requestConfig: ElisRequestConfig<R, Q, P>
+  ) =>
+  (
+    axiosConfig: AxiosRequestConfig
+  ): E.Either<ElisClientError, AxiosRequestConfig> => {
+    const { payload, payloadSchema } = requestConfig;
+    if (!payload || !payloadSchema) {
+      return E.right(axiosConfig);
+    }
+
+    const keyTransform =
+      clientConfig.convertKeys === 'none' ? identity : toSnakeCase;
+
+    const payloadEncoder = asPayloadEncoder(payloadSchema, keyTransform);
+    const resolvedPayload =
+      axiosConfig.headers?.['Content-Type'] === 'multipart/form-data'
+        ? // if we are sending a multipart form with files, create FormData
+          payloadToFormData(payloadEncoder.encode(payload))
+        : // otherwise business as usual
+          payloadEncoder.encode(payload);
+
+    return E.right(
+      merge(axiosConfig, {
+        data: resolvedPayload,
+      })
+    );
+  };
+
+export const buildAxiosConfig = <R, P, Q>(
+  clientConfig: ElisClientConfig,
+  requestConfig: ElisRequestConfig<R, P, Q>
+): E.Either<ElisClientError, AxiosRequestConfig> =>
+  pipe(
+    requestConfig,
+    withRequestConfigDefaults,
+    asAxiosConfig(clientConfig),
+    E.chain(withResponseHeaders(clientConfig, requestConfig)),
+    E.chain(withContentTypeHeaders(clientConfig, requestConfig)),
+    E.chain(withAuthorizationHeader(clientConfig, requestConfig)),
+    E.chain(withTrackingHeader(clientConfig, requestConfig)),
+    E.chain(withAdditionalHeaders(clientConfig, requestConfig)),
+    E.chain(withParams(clientConfig, requestConfig)),
+    E.chain(withData(clientConfig, requestConfig))
+  );

package/src/utils/requestResponse.ts

@@ -0,0 +1,36 @@
+import * as E from 'fp-ts/lib/Either';
+import * as D from 'io-ts/lib/Decoder';
+import { identity } from 'lodash';
+import { DecodingError, ElisClientError } from '../errors';
+import { asResponseDecoder, fromSnakeCase } from '../utils';
+import { ElisClientConfig } from './client';
+import { ElisRequestConfig } from './requestConfig';
+
+export const asDecoded =
+  <R, P, Q>(
+    clientConfig: ElisClientConfig,
+    requestConfig: ElisRequestConfig<R, P, Q>
+  ) =>
+  (data: unknown): E.Either<ElisClientError, R> => {
+    if (requestConfig.responseType !== 'json') {
+      return E.right(data as R);
+    }
+
+    const { endpoint, responseSchema } = requestConfig;
+    const keyTransform =
+      clientConfig.convertKeys === 'none' ? identity : fromSnakeCase;
+
+    const tried = asResponseDecoder(responseSchema, keyTransform).decode(data);
+
+    if (E.isLeft(tried)) {
+      return E.left(
+        new DecodingError({
+          endpoint,
+          decodingOutput: D.draw(tried.left),
+        })
+      );
+    }
+
+    // as R to fix strict null checks - temporary
+    return E.right(tried.right as R);
+  };

package/src/utils/requestUtils.ts

@@ -0,0 +1,37 @@
+// MVP version, it is conceivable this could get more complex - but solve that on API client layer
+export const payloadToFormData = <TPayload extends Record<string, any>>(
+  payload: TPayload
+) => {
+  const fd = new FormData();
+
+  // this does not cover all possible use cases of a request payload
+  // but should do for us long-term
+  // however revisit this next time you are refactoring API client
+
+  // we only use object payloads, so we don't cover other cases
+  if (typeof payload === 'object' && payload !== null) {
+    Object.keys(payload)
+      .filter(key => typeof payload[key] !== 'undefined')
+      .forEach(key => {
+        // if we have a file list, append all files under the same key name one by one
+        // as per https://datatracker.ietf.org/doc/html/rfc7578#page-5 formData spec
+        if (payload[key] instanceof FileList) {
+          Object.keys(payload[key]).forEach(fileKey => {
+            fd.append(key, payload[key][fileKey]);
+          });
+          // if we got object or array, JSON stringify it. FormData automatically calls `.toString()`
+          // on whatever `append` receives so in this cases we would end up with '[object Object]'
+        } else if (
+          Array.isArray(payload[key]) ||
+          typeof payload[key] === 'object'
+        ) {
+          fd.append(key, JSON.stringify(payload[key]));
+          // for primitives, do nothing (calls `toString` automatically)
+        } else {
+          fd.append(key, payload[key]);
+        }
+      });
+  }
+
+  return fd;
+};

package/src/utils/unpaginated.ts

@@ -0,0 +1,38 @@
+import { PaginationQuery } from './listQuery';
+import { ListResponse } from './listResponse';
+
+// wraps a list function so that it always fetches all available items
+// not advisable to use this tho
+export const unpaginated = <Args, TResponseItem>(
+  listFn: (
+    query: Partial<Args & PaginationQuery>
+  ) => Promise<ListResponse<TResponseItem>>
+) => {
+  const recurse = ({
+    page = 1,
+    results = [],
+    query,
+  }: {
+    page: number;
+    results?: TResponseItem[];
+    query: Partial<Args & PaginationQuery>;
+  }): Promise<TResponseItem[]> => {
+    return listFn({ ...query, page }).then(response => {
+      const allResults = [...results, ...response.results];
+
+      if (response?.pagination?.next) {
+        return recurse({
+          page: page + 1,
+          query,
+          results: allResults,
+        });
+      }
+      return allResults;
+    });
+  };
+
+  // start by fetching first page
+  return (query: Partial<Args & PaginationQuery> = {}) => {
+    return recurse({ page: 1, query });
+  };
+};