feat(#9241): create REST API endpoint for getting people

api/src/controllers/person.js

@@ -1,4 +1,4 @@
-const { Person, Qualifier } = require('@medic/cht-datasource');
+const { Person, Qualifier, InvalidArgumentError } = require('@medic/cht-datasource');
 const ctx = require('../services/data-context');
 const serverUtils = require('../server-utils');
 const auth = require('../auth');
@@ -8,20 +8,44 @@ const getPerson = ({ with_lineage }) => ctx.bind(
     ? Person.v1.getWithLineage
     : Person.v1.get
 );
+const getPageByType = () => ctx.bind(Person.v1.getPage);
+
+const checkUserPermissions = async (req) => {
+  const userCtx = await auth.getUserCtx(req);
+  if (!auth.isOnlineOnly(userCtx) || !auth.hasAllPermissions(userCtx, 'can_view_contacts')) {
+    return Promise.reject({ code: 403, message: 'Insufficient privileges' });
+  }
+};
 
 module.exports = {
   v1: {
     get: serverUtils.doOrError(async (req, res) => {
-      const userCtx = await auth.getUserCtx(req);
-      if (!auth.isOnlineOnly(userCtx) || !auth.hasAllPermissions(userCtx, 'can_view_contacts')) {
-        return Promise.reject({ code: 403, message: 'Insufficient privileges' });
-      }
+      await checkUserPermissions(req);
       const { uuid } = req.params;
       const person = await getPerson(req.query)(Qualifier.byUuid(uuid));
       if (!person) {
         return serverUtils.error({ status: 404, message: 'Person not found' }, req, res);
       }
       return res.json(person);
-    })
-  }
+    }),
+    getPageByType: serverUtils.doOrError(async (req, res) => {
+      await checkUserPermissions(req);
+      const personType  = Qualifier.byContactType(req.query.personType);
+      const limit = req.query.limit !== undefined ? Number(req.query.limit) : 100;
+      const skip = req.query.skip !== undefined ? Number(req.query.skip) : 0;
+
+      try {
+        // TODO: change this when #9281 gets merged
+        const docs = await getPageByType()( personType, limit, skip );
+
+        return res.json(docs);
+      } catch (err) {
+        if (err instanceof InvalidArgumentError) {
+          return serverUtils.error({status: 400, message: err.message}, req, res);
+        }
+
+        throw err;
+      }
+    }),
+  },
 };

api/src/routing.js

@@ -480,6 +480,7 @@ app.postJson('/api/v1/people', function(req, res) {
     .catch(err => serverUtils.error(err, req, res));
 });
 
+app.get('/api/v1/person', person.v1.getPageByType);
 app.get('/api/v1/person/:uuid', person.v1.get);
 
 app.postJson('/api/v1/bulk-delete', bulkDocs.bulkDelete);

api/tests/mocha/controllers/person.spec.js

@@ -1,6 +1,6 @@
 const sinon = require('sinon');
 const { expect } = require('chai');
-const { Person, Qualifier } = require('@medic/cht-datasource');
+const { Person, Qualifier, InvalidArgumentError } = require('@medic/cht-datasource');
 const auth = require('../../../src/auth');
 const controller = require('../../../src/controllers/person');
 const dataContext = require('../../../src/services/data-context');
@@ -154,5 +154,113 @@ describe('Person Controller', () => {
         expect(serverUtilsError.calledOnceWithExactly(error, req, res)).to.be.true;
       });
     });
+
+    describe('getPageByType', () => {
+      let personGetPageByType;
+      let qualifierByContactType;
+      const personType = 'person';
+      const invalidPersonType = 'invalidPerson';
+      const personTypeQualifier = { contactType: personType };
+      const person = { name: 'John Doe' };
+      const limit = 100;
+      const skip = 0;
+      const people = Array.from({ length: 3 }, () => ({ ...person }));
+
+      beforeEach(() => {
+        req = {
+          query: {
+            personType,
+            limit,
+            skip
+          }
+        };
+        personGetPageByType = sinon.stub();
+        qualifierByContactType = sinon.stub(Qualifier, 'byContactType');
+        dataContextBind.withArgs(Person.v1.getPage).returns(personGetPageByType);
+        qualifierByContactType.returns(personTypeQualifier);
+      });
+
+      afterEach(() => {
+        expect(getUserCtx.calledOnceWithExactly(req)).to.be.true;
+        expect(isOnlineOnly.calledOnceWithExactly(userCtx)).to.be.true;
+      });
+
+      it('returns a page of people with correct query params', async () => {
+        isOnlineOnly.returns(true);
+        hasAllPermissions.returns(true);
+        personGetPageByType.resolves(people);
+
+        await controller.v1.getPageByType(req, res);
+
+        expect(hasAllPermissions.calledOnceWithExactly(userCtx, 'can_view_contacts')).to.be.true;
+        expect(qualifierByContactType.calledOnceWithExactly(req.query.personType)).to.be.true;
+        expect(dataContextBind.calledOnceWithExactly(Person.v1.getPage)).to.be.true;
+        expect(personGetPageByType.calledOnceWithExactly(personTypeQualifier, limit, skip)).to.be.true;
+        expect(res.json.calledOnceWithExactly(people)).to.be.true;
+        expect(serverUtilsError.notCalled).to.be.true;
+      });
+
+      it('returns error if user does not have can_view_contacts permission', async () => {
+        const error = { code: 403, message: 'Insufficient privileges' };
+        isOnlineOnly.returns(true);
+        hasAllPermissions.returns(false);
+
+        await controller.v1.getPageByType(req, res);
+
+        expect(hasAllPermissions.calledOnceWithExactly(userCtx, 'can_view_contacts')).to.be.true;
+        expect(dataContextBind.notCalled).to.be.true;
+        expect(qualifierByContactType.notCalled).to.be.true;
+        expect(personGetPageByType.notCalled).to.be.true;
+        expect(res.json.notCalled).to.be.true;
+        expect(serverUtilsError.calledOnceWithExactly(error, req, res)).to.be.true;
+      });
+
+      it('returns error if not an online user', async () => {
+        const error = { code: 403, message: 'Insufficient privileges' };
+        isOnlineOnly.returns(false);
+
+        await controller.v1.getPageByType(req, res);
+
+        expect(hasAllPermissions.notCalled).to.be.true;
+        expect(dataContextBind.notCalled).to.be.true;
+        expect(qualifierByContactType.notCalled).to.be.true;
+        expect(personGetPageByType.notCalled).to.be.true;
+        expect(res.json.notCalled).to.be.true;
+        expect(serverUtilsError.calledOnceWithExactly(error, req, res)).to.be.true;
+      });
+
+      it('returns 400 error when argument is invalid', async () => {
+        const errorMessage = `Invalid person type: [${invalidPersonType}]`;
+        const errorPayload = { status: 400, message: errorMessage };
+        isOnlineOnly.returns(true);
+        hasAllPermissions.returns(true);
+        personGetPageByType.throws(new InvalidArgumentError(errorMessage));
+
+        await controller.v1.getPageByType(req, res);
+
+        expect(hasAllPermissions.calledOnceWithExactly(userCtx, 'can_view_contacts')).to.be.true;
+        expect(qualifierByContactType.calledOnceWithExactly(req.query.personType)).to.be.true;
+        expect(dataContextBind.calledOnceWithExactly(Person.v1.getPage)).to.be.true;
+        expect(personGetPageByType.calledOnceWithExactly(personTypeQualifier, limit, skip)).to.be.true;
+        expect(res.json.notCalled).to.be.true;
+        expect(serverUtilsError.calledOnceWithExactly(errorPayload, req, res)).to.be.true;
+      });
+
+      it('rethrows error in case of other errors', async () => {
+        const err = new Error('error');
+        isOnlineOnly.returns(true);
+        hasAllPermissions.returns(true);
+        personGetPageByType.throws(err);
+
+        await controller.v1.getPageByType(req, res);
+
+        expect(hasAllPermissions.calledOnceWithExactly(userCtx, 'can_view_contacts')).to.be.true;
+        expect(qualifierByContactType.calledOnceWithExactly(req.query.personType)).to.be.true;
+        expect(dataContextBind.calledOnceWithExactly(Person.v1.getPage)).to.be.true;
+        expect(personGetPageByType.calledOnceWithExactly(personTypeQualifier, limit, skip)).to.be.true;
+        expect(res.json.notCalled).to.be.true;
+        expect(serverUtilsError.calledOnceWithExactly(err, req, res)).to.be.true;
+      });
+    });
   });
 });

shared-libs/cht-datasource/src/index.ts

@@ -36,6 +36,7 @@ export { Nullable, NonEmptyArray } from './libs/core';
 export { DataContext } from './libs/data-context';
 export { getLocalDataContext } from './local';
 export { getRemoteDataContext } from './remote';
+export { InvalidArgumentError } from './libs/error';
 export * as Person from './person';
 export * as Place from './place';
 export * as Qualifier from './qualifier';
@@ -85,6 +86,20 @@ export const getDatasource = (ctx: DataContext) => {
          * @throws Error if no UUID is provided
          */
         getByUuidWithLineage: (uuid: string) => ctx.bind(Person.v1.getWithLineage)(Qualifier.byUuid(uuid)),
+
+        /**
+         * Returns an array of people for the provided page specifications.
+         * @param personType the type of people to return
+         * @param limit the maximum number of people to return. Default is 100.
+         * @param skip the number of people to skip. Default is 0.
+         * @returns an array of people for the provided page specifications
+         * @throws Error if no type is provided or if the type is not for a person
+         * @throws Error if the provided limit is `<= 0`
+         * @throws Error if the provided skip is `< 0`
+         */
+        getPageByType: (personType: string, limit = 100, skip = 0) => ctx.bind(Person.v1.getPage)(
+          Qualifier.byContactType(personType), limit, skip
+        ),
       }
     }
   };

shared-libs/cht-datasource/src/libs/error.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents an error that occurs when an invalid argument is provided.
+ * This error is typically thrown when a function or method receives an argument
+ * that doesn't meet the expected criteria or constraints.
+ */
+export class InvalidArgumentError extends Error {
+  /**
+   * Constructor
+   * @param message a descriptive error message why the error was raised
+   */
+  constructor(message: string) {
+    super(message);
+    this.name = message;
+
+    Object.setPrototypeOf(this, InvalidArgumentError.prototype);
+  }
+}

shared-libs/cht-datasource/src/local/libs/doc.ts

@@ -27,15 +27,25 @@ export const getDocsByIds = (db: PouchDB.Database<Doc>) => async (uuids: string[
     .filter((doc): doc is Doc => isDoc(doc));
 };
 
+const queryDocs = (db: PouchDB.Database<Doc>, view: string, options: PouchDB.Query.Options<Doc, unknown>) => db
+  .query(view, {...options})
+  .then(({ rows }) => rows.map(({ doc }) => isDoc(doc) ? doc : null));
+
 /** @internal */
-export const queryDocsByKey = (
+export const queryDocsByRange = (
   db: PouchDB.Database<Doc>,
   view: string
-) => async (key: string): Promise<Nullable<Doc>[]> => db
-  .query(view, {
-    startkey: [key],
-    endkey: [key, {}],
-    include_docs: true
-  })
-  .then(({ rows }) => rows.map(({ doc }) => isDoc(doc) ? doc : null));
+) => async (
+  startkey: unknown,
+  endkey: unknown
+): Promise<Nullable<Doc>[]> => queryDocs(db, view, { include_docs: true, startkey, endkey});
 
+/** @internal */
+export const queryDocsByKey = (
+  db: PouchDB.Database<Doc>,
+  view: string
+) => async (
+  key: unknown,
+  limit: number,
+  skip: number
+): Promise<Nullable<Doc>[]> => queryDocs(db, view, { include_docs: true, key, limit, skip });

shared-libs/cht-datasource/src/local/libs/lineage.ts

@@ -10,17 +10,18 @@ import {
   Nullable
 } from '../../libs/core';
 import { Doc } from '../../libs/doc';
-import { queryDocsByKey } from './doc';
+import { queryDocsByRange } from './doc';
 import logger from '@medic/logger';
 
 /**
  * Returns the identified document along with the parent documents recorded for its lineage. The returned array is
  * sorted such that the identified document is the first element and the parent documents are in order of lineage.
  * @internal
  */
-export const getLineageDocsById = (
-  medicDb: PouchDB.Database<Doc>
-): (id: string) => Promise<Nullable<Doc>[]> => queryDocsByKey(medicDb, 'medic-client/docs_by_id_lineage');
+export const getLineageDocsById = (medicDb: PouchDB.Database<Doc>): (id: string) => Promise<Nullable<Doc>[]> => {
+  const fn = queryDocsByRange(medicDb, 'medic-client/docs_by_id_lineage');
+  return (id: string) => fn([id], [id, {}]);
+};
 
 /** @internal */
 export const getPrimaryContactIds = (places: NonEmptyArray<Nullable<Doc>>): string[] => places

shared-libs/cht-datasource/src/local/person.ts

@@ -1,16 +1,17 @@
 import { Doc } from '../libs/doc';
 import contactTypeUtils from '@medic/contact-types-utils';
 import { deepCopy, isNonEmptyArray, Nullable } from '../libs/core';
-import { UuidQualifier } from '../qualifier';
+import { ContactTypeQualifier, UuidQualifier } from '../qualifier';
 import * as Person from '../person';
-import { getDocById, getDocsByIds } from './libs/doc';
+import { getDocById, getDocsByIds, queryDocsByKey } from './libs/doc';
 import { LocalDataContext, SettingsService } from './libs/data-context';
 import logger from '@medic/logger';
 import { getLineageDocsById, getPrimaryContactIds, hydrateLineage, hydratePrimaryContact } from './libs/lineage';
+import {InvalidArgumentError} from '../libs/error';
 
 /** @internal */
 export namespace v1 {
-  const isPerson = (settings: SettingsService, uuid: string, doc: Nullable<Doc>): doc is Person.v1.Person => {
+  const isPerson = (settings: SettingsService, doc: Nullable<Doc>, uuid = ''): doc is Person.v1.Person => {
     if (!doc) {
       logger.warn(`No person found for identifier [${uuid}].`);
       return false;
@@ -28,7 +29,7 @@ export namespace v1 {
     const getMedicDocById = getDocById(medicDb);
     return async (identifier: UuidQualifier): Promise<Nullable<Person.v1.Person>> => {
       const doc = await getMedicDocById(identifier.uuid);
-      if (!isPerson(settings, identifier.uuid, doc)) {
+      if (!isPerson(settings, doc, identifier.uuid)) {
         return null;
       }
       return doc;
@@ -41,7 +42,7 @@ export namespace v1 {
     const getMedicDocsById = getDocsByIds(medicDb);
     return async (identifier: UuidQualifier): Promise<Nullable<Person.v1.PersonWithLineage>> => {
       const [person, ...lineagePlaces] = await getLineageDocs(identifier.uuid);
-      if (!isPerson(settings, identifier.uuid, person)) {
+      if (!isPerson(settings, person, identifier.uuid)) {
         return null;
       }
       // Intentionally not further validating lineage. For passivity, lineage problems should not block retrieval.
@@ -58,4 +59,22 @@ export namespace v1 {
       return deepCopy(personWithLineage);
     };
   };
+
+  /** @internal */
+  export const getPage = ({ medicDb, settings }: LocalDataContext) => {
+    return async (personType: ContactTypeQualifier, limit: number, skip: number): Promise<Person.v1.Person[]> => {
+      const personTypes = contactTypeUtils.getPersonTypes(settings.getAll());
+      const personTypesIds = personTypes.map(item => item.id);
+
+      if (!personTypesIds.includes(personType.contactType)) {
+        throw new InvalidArgumentError(`Invalid person type: ${personType.contactType}`);
+      }
+
+      const getDocsByPage = queryDocsByKey(medicDb, 'medic-client/contacts_by_type');
+
+      const docs = await getDocsByPage([personType.contactType], limit, skip);
+
+      return docs.filter((doc): doc is Person.v1.Person => isPerson(settings, doc, doc?._id));
+    };
+  };
 }