@openstax/ts-utils 1.33.1 → 1.34.0

package/packages/utils/src/services/accountsGateway/index.ts

@@ -0,0 +1,251 @@
+
+import { chunk, isEqual } from 'lodash';
+import queryString from 'query-string';
+import { ConfigProviderForConfig, resolveConfigValue } from '../../config';
+import { FetchConfig, GenericFetch } from '../../fetch';
+import { ifDefined, isDefined } from '../../guards';
+import { once } from '../../misc/helpers';
+import { JsonCompatibleStruct, METHOD } from '../../routing';
+import { ApiUser, ConsentPreferences } from '../authProvider';
+import { Level, Logger } from '../logger';
+
+export type Config = {
+  accountsBase: string;
+  accountsAuthToken: string;
+};
+interface Initializer<C> {
+  configSpace?: C;
+  fetch: GenericFetch;
+}
+
+export type FindUserPayload = ({ external_id: string } | { uuid: string }) & { sso?: string };
+
+export type FindOrCreateUserPayload = {
+  external_id: string;
+  email?: string;
+  already_verified?: boolean;
+  first_name?: string;
+  last_name?: string;
+  full_name?: string;
+  salesforce_contact_id?: string;
+  faculty_status?: string;
+  role?: string;
+  school_type?: string;
+  is_test?: boolean;
+  sso?: string;
+};
+
+export type FindOrCreateUserResponse = {
+  id: number;
+  uuid: string;
+  external_ids: string[];
+  is_test: boolean;
+  sso: string;
+};
+
+export type FindUserResponse = (FindOrCreateUserResponse & { external_ids: string[] }) | undefined;
+
+export type LinkUserPayload = {
+  userId: number;
+  externalId: string;
+};
+
+export type LinkUserResponse = {
+  user_id: number;
+  external_id: string;
+};
+
+export type SearchUsersPayload = {
+  q: string;
+  order_by?: string;
+};
+
+export type SearchUsersResponse = {
+  // Extension can be removed when typescript-service-template is updated
+  items: Array<ApiUser & {external_ids: string[]} & JsonCompatibleStruct>;
+  total_count: number;
+};
+
+// Change this to a Partial if we add another field that can be updated
+export type UpdateUserPayload = ConsentPreferences;
+
+class ApiError extends Error {
+  status: number;
+
+  constructor(message: string, status: number) {
+    super(message);
+    this.status = status;
+  }
+}
+
+export type MappedUserInfo<T> = { data: T; fullName: string; platformUserId?: string; uuid: string };
+
+export const accountsGateway = <C extends string = 'accounts'>(initializer: Initializer<C>) => (configProvider: {[_key in C]: ConfigProviderForConfig<Config>}) => {
+  const config = configProvider[ifDefined(initializer.configSpace, 'accounts' as C)];
+  const accountsBase = once(() => resolveConfigValue(config.accountsBase));
+  const accountsAuthToken = once(() => resolveConfigValue(config.accountsAuthToken));
+
+  return ({logger}: { logger: Logger }) => {
+    const request = async(
+      method: METHOD,
+      path: string,
+      options: {body?: object; token?: string},
+      statuses = [200, 201]
+    ) => {
+      const host = (await accountsBase()).replace(/\/+$/, '');
+      const url = `${host}/api/${path}`;
+
+      const config: FetchConfig = {
+        headers: {
+          Authorization: `Bearer ${options.token || await accountsAuthToken()}`,
+        },
+        method,
+      };
+      if (options.body) { config.body = JSON.stringify(options.body); }
+
+      const response = await initializer.fetch(url, config);
+      if (!statuses.includes(response.status)) {
+        throw new ApiError(
+          `Received unexpected status code ${response.status} for Accounts API call: ${method} ${url}`,
+          response.status
+        );
+      }
+
+      return response.json();
+    };
+
+    const findOrCreateUser = async(body: FindOrCreateUserPayload): Promise<FindOrCreateUserResponse> => request(
+      METHOD.POST, 'user/find-or-create', {body}
+    );
+
+    const findUser = async(body: FindUserPayload): Promise<FindUserResponse> => {
+      try {
+        return await request(METHOD.POST, 'user/find', {body});
+      } catch (error: any) {
+        if (error instanceof ApiError && error.status === 404) {
+          return undefined;
+        } else {
+          throw error;
+        }
+      }
+    };
+
+    const getUser = async(token: string): Promise<ApiUser & JsonCompatibleStruct> => request(
+      METHOD.GET, 'user', {token}
+    );
+
+    const linkUser = async(body: LinkUserPayload): Promise<LinkUserResponse> => request(
+      METHOD.POST, 'user/external-ids', {
+        body: {
+          external_id: body.externalId,
+          user_id: body.userId,
+        }
+      }
+    );
+
+    const searchUsers = async(payload: SearchUsersPayload): Promise<SearchUsersResponse> => request(
+      METHOD.GET, `users?${queryString.stringify(payload)}`, {}
+    );
+
+    const updateUser = async(
+      token: string, body: UpdateUserPayload
+    ): Promise<ApiUser & JsonCompatibleStruct> => request(METHOD.PUT, 'user', {body, token});
+
+    const getPlatformUserId = (externalIds: string[], platformId: string) => {
+      for (const externalId of externalIds) {
+        const [userPlatformId, userId] = externalId.split('/', 2);
+        if (userPlatformId === platformId) {
+          return userId;
+        }
+      }
+    };
+
+    /*
+     * If a platformId is given, returns an array where
+     * the first element is the user id from the platform
+     * and the second is the value from the map
+     * Otherwise, returns an array where
+     * the first element is the user's full_name
+     * and the second is the value from the map
+     */
+    const mapUserUuids = async<T>(
+      userUuidsMap: { [uuid: string]: T },
+      platformId?: string
+    ) => {
+      const results = await mapUserData(Object.entries(userUuidsMap), ([id]) => id, (user, [, data]) => {
+        if (!user) return undefined;
+        const platformUserId = platformId ? getPlatformUserId(user.external_ids, platformId) : undefined;
+
+        if (platformId && !platformUserId) {
+          logger.logEvent(Level.Warn, {
+            message: 'Accounts user has no external_id matching the given platformId',
+            accountsUuid: user.uuid,
+            platformId,
+          });
+        }
+
+        if (!user.full_name) {
+          logger.logEvent(Level.Warn, {
+            message: 'Accounts user has no full_name',
+            accountsUuid: user.uuid,
+          });
+        }
+
+        return {data, fullName: user.full_name, platformUserId, uuid: user.uuid};
+      });
+
+      return results.filter(isDefined);
+    };
+
+    const getUserMap = async <R>(
+      userUuids: Set<string>,
+      mapper: ((user: ApiUser) => R)
+    ): Promise<Map<string, R>> => {
+      if (userUuids.size === 0) return new Map();
+
+      const chunked = chunk([...userUuids], 10);
+      const results = await Promise.all(chunked.map(async(inputChunk) => {
+        const {items} = await searchUsers({q:
+          inputChunk.map(userUuid => `uuid:${userUuid}`).join(' ')
+        });
+        const accountsUuids = items.map((user) => user.uuid);
+
+        if (!isEqual(accountsUuids.sort(), inputChunk.sort())) {
+          logger.logEvent(Level.Warn, {
+            message: 'Unexpected Accounts user search results',
+            uuids: inputChunk,
+            accountsUuids,
+          });
+        }
+        return items;
+      }));
+
+      return new Map(results.flat(1).map(user => [user.uuid, mapper(user)]));
+    };
+
+    const mapUserData = async <T, R>(
+      input: T[],
+      getUserUuid: (item: T) => string,
+      mapper: ((user: ApiUser | undefined, item: T) => R)
+    ): Promise<R[]> => {
+      const userMap = await getUserMap(new Set(input.flatMap(getUserUuid)), user => user);
+      return input.map(item => mapper(userMap.get(getUserUuid(item)), item));
+    };
+    const mapUsersData = async <T, R>(
+      input: T[],
+      getUserUuids: (item: T) => string[],
+      mapper: ((users: Map<string, ApiUser | undefined>, item: T) => R)
+    ): Promise<R[]> => {
+      const userMap = await getUserMap(new Set(input.flatMap(getUserUuids)), user => user);
+      return input.map(item => {
+        const userUuids = getUserUuids(item);
+        const itemUserMap = new Map(userUuids.map(uuid => [uuid, userMap.get(uuid)]));
+        return mapper(itemUserMap, item);
+      });
+    };
+
+    return { findOrCreateUser, findUser, getUser, linkUser, mapUserUuids, searchUsers, updateUser, getUserMap, mapUserData, mapUsersData };
+  };
+};
+
+export type AccountsGateway = ReturnType<ReturnType<ReturnType<typeof accountsGateway>>>;

package/packages/utils/src/services/apiGateway/README.md

@@ -0,0 +1,93 @@
+# ApiGateway
+
+the apiGateway library creates an api client based on routes defined using the routing helper.
+
+example code to create an api gateway:
+
+```typescript
+// route definitions are imported directly from api code
+import {TRoutes as ApiRoutes} from '@my-project/lambdas/build/src/functions/myApi/core/routes';
+// runtime config is just method and path, this script exports that, and we're using val-loader to avoid pulling the whole
+// api codebase into the UI bundle
+import routes from '!!val-loader!@my-project/lambdas/build/script/utils/routeDataLoader';
+import { AppServices } from "../core/types";
+import {assertDefined} from "@openstax/ts-utils/assertions";
+
+const config = {
+  // the envConfig doesn't work in Create-React-App right now
+  apiBase: () => process.env.NODE_ENV === 'production'
+    ? assertDefined(process.env.REACT_APP_API_BASE_URL, 'REACT_APP_API_BASE_URL must be provided in production')
+    : '/'
+};
+
+export const createApiClient = (app: AppServices) => {
+  return app.createApiGateway<ApiRoutes>(config, routes, app);
+};
+
+export const useApiClient = () => {
+  const services = useServices(); // get services from somewhere
+  const apiClientRef = React.useRef(createApiClient(services));
+  return apiClientRef.current;
+};
+
+```
+
+example usages of the api
+
+```typescript
+const apiClient = useApiClient();
+
+// this example loads a resource and fails if it can't
+apiClient.getAThing({params: {id: 'someId'}})
+  .then(response => response.acceptStatus(200))
+  .then(response => response.load())
+  .then(thingData => {
+    console.log(thingData);
+  })
+  .catch(e => {
+    console.error(e);
+  })
+;
+
+// this example loads a thing but resolves `undefined` if its missing, and fails if there is any other response
+apiClient.getAThing({params: {id: 'someId'}})
+  .then(response => response.acceptStatus(200, 404)) // accept status throws if the response is unexpected
+  .then(response => response.status === 200 ? response.load() : undefined);
+  .then(thingDataOrUndefined => {
+    console.log(thingDataOrUndefined);
+  })
+  .catch(e => {
+    console.error(e);
+  })
+
+// the renderUrl helper just gives the string for the url with the given params and arguments
+apiClient.getAThing.renderUrl({
+  params: {id: 'someId'},
+  query: {
+    otherOptions: ['cool', 'option'],
+  }
+})
+  .then(url => {
+    console.log(url);
+  });
+;
+
+// a form submit handler that posts to an endpoint using react and fetch state helpers
+const [saveState, setSaveState] = React.useState<FetchState<MyDocument, string>>();
+const saveHandler = (e: React.FormEvent<HTMLFormElement>) => {
+  e.preventDefault();
+  setSaveState(fetchLoading(data));
+  const formData = new FormData(e.target as HTMLFormElement);
+
+  apiClient.saveAThing({params: {id: uuid()}, payload: {
+    title: assertString(formData.get('title'), 'form data should be a string'),
+  }})
+    .then(response => response.acceptStatus(201))
+    .then(response => response.load())
+    .then(data => {
+      setSaveState(fetchSuccess(data));
+    })
+    .catch(() => setSaveState(fetchError('save failed')))
+  ;
+};
+```

package/packages/utils/src/services/apiGateway/index.spec.ts

@@ -0,0 +1,254 @@
+import { SessionExpiredError, UnauthorizedError } from '../../errors';
+import { apiJsonResponse, apiTextResponse, HttpHeaders, makeCreateRoute, requestPayloadProvider, unsafePayloadValidator } from '../../routing';
+import { stubAuthProvider, User } from '../authProvider';
+import { Logger } from '../logger';
+import { createApiGateway, loadResponse } from '.';
+
+const createRoute = makeCreateRoute<{}, string, {}>();
+
+const routeOne = createRoute({
+  handler: () => apiJsonResponse(200, { message: 'response one' }),
+  path: '/routeOnePath',
+  name: 'routeOne',
+});
+
+const routeTwo = createRoute({
+  path: '/routeTwoPath/:foo',
+  name: 'routeTwo',
+  handler: (_: { foo: string }) => apiTextResponse(200, 'response two')
+});
+
+const routeConfig = {
+  routeOne: {
+    path: '/routeOnePath',
+    method: 'GET',
+  },
+  routeTwo: {
+    path: '/routeTwoPath/:foo',
+    method: 'GET',
+  },
+};
+
+type TRoutes = typeof routeOne | typeof routeTwo;
+
+describe('createApiGateway', () => {
+
+  const mockLogger: Logger = {
+    logEvent: jest.fn(),
+    setContext: jest.fn(),
+    log: jest.fn(),
+    createSubContext: jest.fn().mockReturnValue({ log: jest.fn(), setContext: jest.fn() }),
+  };
+
+  it('defines route clients', () => {
+    const fetch = jest.fn();
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig, { logger: mockLogger });
+
+    expect(client.routeOne).toBeDefined();
+    expect(client.routeTwo).toBeDefined();
+  });
+
+  it('makes requests', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({}) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig);
+
+    await client.routeOne({});
+
+    expect(fetch).toHaveBeenCalledWith('/base/routeOnePath', expect.anything());
+  });
+
+  it('makes requests with param', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({}) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig);
+
+    await client.routeTwo({ params: { foo: 'param' } });
+
+    expect(fetch).toHaveBeenCalledWith('/base/routeTwoPath/param', expect.anything());
+  });
+
+  it('makes requests with query', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({}) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig, { authProvider: stubAuthProvider() });
+
+    await client.routeOne({ query: { thing: 'value' } });
+
+    expect(fetch).toHaveBeenCalledWith('/base/routeOnePath?thing=value', expect.anything());
+
+  });
+
+  it('passes headers', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({}) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig, { logger: mockLogger });
+
+    await client.routeOne({
+      fetchConfig: {
+        headers: {
+          custom: 'header'
+        }
+      }
+    });
+
+    expect(fetch).toHaveBeenCalledWith('/base/routeOnePath', expect.objectContaining({
+      headers: {
+        custom: 'header',
+        'x-request-id': expect.any(String)
+      }
+    }));
+  });
+
+  it('passes launch token header', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({}) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig, { logger: mockLogger, launchToken: 'token' });
+
+    await client.routeOne({
+      fetchConfig: {
+        headers: {
+          custom: 'header'
+        }
+      }
+    });
+
+    expect(fetch).toHaveBeenCalledWith('/base/routeOnePath', expect.objectContaining({
+      headers: {
+        custom: 'header',
+        'x-launch-token': 'token',
+        'x-request-id': expect.any(String)
+      }
+    }));
+  });
+
+  it('handles no headers from auth', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({}) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig, { authProvider: stubAuthProvider(), logger: mockLogger });
+
+    await client.routeOne({});
+
+    expect(fetch).toHaveBeenCalledWith('/base/routeOnePath', expect.anything());
+  });
+
+  it('passes headers from authProvider', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({}) }));
+
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig, { authProvider: stubAuthProvider({ uuid: 'uuid' } as unknown as User) });
+
+    await client.routeOne({});
+
+    expect(fetch).toHaveBeenCalledWith('/base/routeOnePath', expect.objectContaining({
+      headers: {
+        Authorization: 'uuid',
+        'x-request-id': expect.any(String)
+      }
+    }));
+  });
+
+  it('makes posts', async () => {
+    const createRouteWithHttpStuff = makeCreateRoute<{}, { headers: HttpHeaders; body: string | undefined }, {}>();
+    const postRoute = createRouteWithHttpStuff({
+      path: '/routePath',
+      name: 'route',
+      requestServiceProvider: requestPayloadProvider(unsafePayloadValidator<{ foobar: string }>())
+    },
+      () => apiTextResponse(200, 'response')
+    );
+    const postRouteConfig = {
+      route: {
+        path: '/routePath',
+        method: 'POST',
+      },
+    };
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve('response') }));
+    const client = createApiGateway({ fetch })<typeof postRoute>({ apiBase: '/base' }, postRouteConfig);
+
+    await client.route({ payload: { foobar: 'asdf' } });
+
+    expect(fetch).toHaveBeenCalledWith('/base/routePath', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-request-id': expect.any(String)
+      },
+      body: '{"foobar":"asdf"}'
+    });
+  });
+
+  it('loads json', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({ message: 'response one' }) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig);
+
+    expect(await client.routeOne({})
+      .then(response => response.load())).toEqual({ message: 'response one' });
+  });
+
+  it('accepts status', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({ message: 'response one' }) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig);
+
+    expect(await client.routeOne({})
+      .then(response => response.acceptStatus(200))
+      .then(response => response.load())).toEqual({ message: 'response one' });
+  });
+
+  it('rejects status', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 200, headers: { get: () => 'application/json' }, json: () => Promise.resolve({ message: 'response one' }) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig);
+
+    await expect(
+      client.routeOne({})
+        .then(response => response.acceptStatus(201))
+        .then(response => response.load())
+    ).rejects.toThrow();
+  });
+
+  it('throws UnauthorizedError when the status is 401', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 401, headers: { get: () => 'application/json' }, json: () => Promise.resolve({ message: '401 UnauthorizedError' }) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig);
+
+    await expect(
+      client.routeOne({})
+        .then(response => response.acceptStatus(200))
+        .then(response => response.load())
+    ).rejects.toThrow(UnauthorizedError);
+  });
+
+  it('throws SessionExpiredError when the status is 440', async () => {
+    const fetch = jest.fn().mockReturnValue(Promise.resolve({ status: 440, headers: { get: () => 'application/json' }, json: () => Promise.resolve({ message: '440 SessionExpiredError' }) }));
+    const client = createApiGateway({ fetch })<TRoutes>({ apiBase: '/base' }, routeConfig);
+
+    await expect(
+      client.routeOne({})
+        .then(response => response.acceptStatus(200))
+        .then(response => response.load())
+    ).rejects.toThrow(SessionExpiredError);
+  });
+
+});
+
+describe('loadResponse', () => {
+  it('decodes json', () => {
+    const json = jest.fn();
+    loadResponse({ status: 200, headers: { get: () => 'application/json' }, json } as any)();
+    expect(json).toHaveBeenCalled();
+  });
+
+  it('decodes text', () => {
+    const text = jest.fn();
+    loadResponse({ status: 200, headers: { get: () => 'text/plain' }, text } as any)();
+    expect(text).toHaveBeenCalled();
+  });
+
+  it('decodes text with charset', () => {
+    const text = jest.fn();
+    loadResponse({ status: 200, headers: { get: () => 'text/plain; charset=utf-8' }, text } as any)();
+    expect(text).toHaveBeenCalled();
+  });
+
+  it('throws', () => {
+    expect(() => loadResponse(({ status: 200, headers: { get: () => 'asdf' } } as any))()).
+      toThrowErrorMatchingInlineSnapshot('"unknown content type asdf"');
+  });
+
+  it('throws with missing', () => {
+    expect(() => loadResponse(({ status: 200, headers: { get: () => undefined } } as any))()).
+      toThrowErrorMatchingInlineSnapshot('"unknown content type "');
+  });
+});