feat(#10706): add api endpoints for advanced contact management operations

api/src/controllers/archive.js

@@ -0,0 +1,101 @@
+const readline = require('node:readline');
+const { v7: uuid } = require('uuid');
+const logger = require('@medic/logger');
+const archivingUtils = require('@medic/archiving-utils');
+const constants = require('@medic/constants');
+
+const db = require('../db');
+const auth = require('../auth');
+const serverUtils = require('../server-utils');
+const errors = require('../errors');
+
+const MAX_IDS_PER_JOB = 100 * 1000;
+const EXPECTED_CONTENT_TYPE = 'text/csv';
+const parseCell = (line) => line.trim().replace(/^"(.*)"$/, '$1');
+
+const checkAdmin = async (req) => {
+  const userCtx = await auth.getUserCtx(req);
+  if (!auth.isDbAdmin(userCtx)) {
+    throw new errors.AuthenticationError('User is not an admin');
+  }
+};
+
+const checkContentType = (req) => {
+  if (!req.is(EXPECTED_CONTENT_TYPE)) {
+    throw new errors.ContentTypeError(`Content-Type must be ${EXPECTED_CONTENT_TYPE}`);
+  }
+};
+
+const buildJobId = () => `${constants.PREFIXES.ARCHIVE_JOB}${uuid()}`;
+
+const persistJob = async (jobs, ids) => {
+  if (!ids.length) {
+    return;
+  }
+
+  const doc = {
+    _id: buildJobId(),
+    type: constants.PREFIXES.ARCHIVE_JOB,
+    date: Date.now(),
+    total: ids.length,
+    cursor: 0,
+    _attachments: {
+      [archivingUtils.ATTACHMENT_NAME]: {
+        content_type: archivingUtils.ATTACHMENT_TYPE,
+        data: archivingUtils.encodeIds(ids),
+      },
+    },
+  };
+
+  await db.sentinel.put(doc);
+  jobs.push({ id: doc._id, count: doc.total });
+};
+
+const flushIfFull = async (jobs, buffer) => {
+  if (buffer.length < MAX_IDS_PER_JOB) {
+    return buffer;
+  }
+  await persistJob(jobs, buffer);
+  return [];
+};
+
+const processPayload = async (req) => {
+  const jobs = [];
+  let buffer = [];
+  const rl = readline.createInterface({ input: req, crlfDelay: Infinity });
+
+  for await (const line of rl) {
+    const id = parseCell(line);
+    if (!id) {
+      continue;
+    }
+    buffer.push(id);
+    buffer = await flushIfFull(jobs, buffer);
+  }
+
+  await persistJob(jobs, buffer);
+
+  if (!jobs.length) {
+    throw new errors.BadRequestError('No valid doc IDs found in request body');
+  }
+  return jobs;
+};
+
+module.exports = {
+  create: async (req, res) => {
+    try {
+      await checkAdmin(req);
+      checkContentType(req);
+    } catch (err) {
+      return serverUtils.error(err, req, res);
+    }
+
+    try {
+      const jobs = await processPayload(req);
+      res.status(201).json({ jobs });
+    } catch (err) {
+      logger.error('Failed to create archive jobs: %o', err);
+      return serverUtils.error(err, req, res);
+    }
+  },
+};

api/src/controllers/bulk-operations.js

@@ -0,0 +1,80 @@
+const service = require('../services/bulk-operations');
+const serverUtils = require('../server-utils');
+const auth = require('../auth');
+
+module.exports = {
+  v1: {
+    /**
+     * @openapi
+     * /api/v1/bulk-operations/{id}:
+     *   get:
+     *     summary: Get the status of a bulk operation
+     *     operationId: v1BulkOperationIdGet
+     *     description: >
+     *       Returns the log document for a bulk operation, including the per-action status and the
+     *       count of changes applied so far. Used to poll the progress of an operation that was
+     *       started through one of the bulk endpoints. The bulk operation can be considered finished
+     *       when all of its actions have a status of "completed" or "failed".
+     *     tags: [Bulk]
+     *     x-since: 5.3.0
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: The id of the bulk operation, as returned when it was started.
+     *     responses:
+     *       '200':
+     *         description: The bulk operation log
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               properties:
+     *                 _id:
+     *                   type: string
+     *                   description: The bulk operation id.
+     *                 start_date:
+     *                   type: string
+     *                   format: date-time
+     *                   description: When the operation was started.
+     *                 actions:
+     *                   type: object
+     *                   description: Per-action status, keyed by action id.
+     *                   additionalProperties:
+     *                     type: object
+     *                     properties:
+     *                       status:
+     *                         type: string
+     *                         enum: [queued, completed, failed]
+     *                       action:
+     *                         type: string
+     *                         enum: [archive, set-contact, delete-user]
+     *                       updated_date:
+     *                         type: string
+     *                         format: date-time
+     *                       total_changes_count:
+     *                         type: integer
+     *                       failed_operations:
+     *                         type: array
+     *                         description: The operations that failed, present only when status is failed.
+     *                         items:
+     *                           type: object
+     *       '401':
+     *         $ref: '#/components/responses/Unauthorized'
+     *       '403':
+     *         $ref: '#/components/responses/Forbidden'
+     *       '404':
+     *         $ref: '#/components/responses/NotFound'
+     */
+    get: serverUtils.doOrError(async (req, res) => {
+      await auth.assertPermissions(req, { isOnline: true });
+      const log = await service.getLog(req.params.id);
+      if (!log) {
+        return serverUtils.error({ status: 404, message: 'Bulk operation not found' }, req, res);
+      }
+      res.json(log);
+    })
+  }
+};

api/src/controllers/person.js

@@ -2,6 +2,7 @@ const { Person, Qualifier } = require('@medic/cht-datasource');
 const ctx = require('../services/data-context');
 const serverUtils = require('../server-utils');
 const auth = require('../auth');
+const deleteContactService = require('../services/delete-contact');
 
 const getPerson = ctx.bind(Person.v1.get);
 const getPersonWithLineage = ctx.bind(Person.v1.getWithLineage);
@@ -208,5 +209,48 @@ module.exports = {
       const updatedPersonDoc = await updatePerson(updatePersonInput);
       return res.json(updatedPersonDoc);
     }),
+
+    /**
+     * @openapi
+     * /api/v1/person/{id}:
+     *   delete:
+     *     summary: Delete a person
+     *     operationId: v1PersonIdDelete
+     *     description: >
+     *       Queues an asynchronous bulk operation that removes the person and the reports they are the
+     *       subject of, clears any dangling primary-contact references, and (with delete_users=true)
+     *       removes linked user accounts. Returns a summary of the changes and the bulk operation id
+     *       to poll.
+     *     tags: [Person]
+     *     x-since: 5.3.0
+     *     x-permissions:
+     *       hasAll: [can_delete_contact_hierarchy, can_delete_users]
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: The id of the person to delete
+     *       - $ref: '#/components/parameters/deleteUsers'
+     *       - $ref: '#/components/parameters/dryRun'
+     *     responses:
+     *       '202':
+     *         $ref: '#/components/responses/BulkOperationQueued'
+     *       '200':
+     *         $ref: '#/components/responses/BulkOperationDryRun'
+     *       '400':
+     *         $ref: '#/components/responses/BadRequest'
+     *       '401':
+     *         $ref: '#/components/responses/Unauthorized'
+     *       '403':
+     *         $ref: '#/components/responses/Forbidden'
+     *       '404':
+     *         $ref: '#/components/responses/NotFound'
+     */
+    delete: deleteContactService.handleDelete({
+      get: (uuid) => getPerson(Qualifier.byUuid(uuid)),
+      type: 'Person',
+    }),
   },
 };

api/src/controllers/place.js

@@ -2,6 +2,7 @@ const { Place, Qualifier } = require('@medic/cht-datasource');
 const ctx = require('../services/data-context');
 const serverUtils = require('../server-utils');
 const auth = require('../auth');
+const deleteContactService = require('../services/delete-contact');
 
 const getPlace = ctx.bind(Place.v1.get);
 const getPlaceWithLineage = ctx.bind(Place.v1.getWithLineage);
@@ -214,6 +215,49 @@ module.exports = {
       };
       const updatedPlaceDoc = await update(updatePlaceInput);
       return res.json(updatedPlaceDoc);
+    }),
+
+    /**
+     * @openapi
+     * /api/v1/place/{id}:
+     *   delete:
+     *     summary: Delete a place and its hierarchy
+     *     operationId: v1PlaceIdDelete
+     *     description: >
+     *       Queues an asynchronous bulk operation that removes the place, every descendant contact,
+     *       and the reports they are the subject of, clears any dangling primary-contact references,
+     *       and (with delete_users=true) removes linked user accounts. Returns a summary of the
+     *       changes and the bulk operation id to poll.
+     *     tags: [Place]
+     *     x-since: 5.3.0
+     *     x-permissions:
+     *       hasAll: [can_delete_contact_hierarchy, can_delete_users]
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: The id of the place to delete
+     *       - $ref: '#/components/parameters/deleteUsers'
+     *       - $ref: '#/components/parameters/dryRun'
+     *     responses:
+     *       '202':
+     *         $ref: '#/components/responses/BulkOperationQueued'
+     *       '200':
+     *         $ref: '#/components/responses/BulkOperationDryRun'
+     *       '400':
+     *         $ref: '#/components/responses/BadRequest'
+     *       '401':
+     *         $ref: '#/components/responses/Unauthorized'
+     *       '403':
+     *         $ref: '#/components/responses/Forbidden'
+     *       '404':
+     *         $ref: '#/components/responses/NotFound'
+     */
+    delete: deleteContactService.handleDelete({
+      get: (uuid) => getPlace(Qualifier.byUuid(uuid)),
+      type: 'Place',
     })
   }
 };

api/src/db.js

@@ -23,6 +23,7 @@ if (UNIT_TEST_ENV) {
     'builds',
     'vault',
     'cache',
+    'archive',
   ];
   const DB_FUNCTIONS_TO_STUB = [
     'allDocs',
@@ -103,6 +104,7 @@ if (UNIT_TEST_ENV) {
   module.exports.vault = new PouchDB(`${environment.couchUrl}-vault`, { fetch: fetchFn });
   module.exports.createVault = () => module.exports.vault.info();
   module.exports.users = new PouchDB(getDbUrl('_users'), { fetch: fetchFn });
+  module.exports.archive = new PouchDB(`${environment.couchUrl}-archive`, { fetch: fetchFn });
   module.exports.builds = new PouchDB(environment.buildsUrl);
 
   // Get the DB with the given name

api/src/errors.js

@@ -27,9 +27,26 @@ class AuthenticationError extends Error {
   }
 }
 
+class ContentTypeError extends Error {
+  constructor(message, ...args) {
+    super(message, ...args);
+    this.code = 415;
+  }
+}
+
+class BadRequestError extends Error {
+  constructor(message, ...args) {
+    super(message, ...args);
+    this.code = 400;
+  }
+}
+
+
 module.exports = {
   PublicError,
   NotFoundError,
   PermissionError,
   AuthenticationError,
+  ContentTypeError,
+  BadRequestError,
 };

api/src/routing.js

@@ -46,13 +46,15 @@ const { people, places } = require('@medic/contacts')(config, db, dataContext);
 const upgrade = require('./controllers/upgrade');
 const settings = require('./controllers/settings');
 const bulkDocs = require('./controllers/bulk-docs');
+const bulkOperations = require('./controllers/bulk-operations');
 const monitoring = require('./controllers/monitoring');
 const africasTalking = require('./controllers/africas-talking');
 const rapidPro = require('./controllers/rapidpro');
 const infodoc = require('./controllers/infodoc');
 const impact = require('./controllers/impact');
 const targetController = require('./controllers/target');
 const credentials = require('./controllers/credentials');
+const archive = require('./controllers/archive');
 const authorization = require('./middleware/authorization');
 const deprecation = require('./middleware/deprecation');
 const hydration = require('./controllers/hydration');
@@ -476,6 +478,8 @@ app.get('/api/v1/monitoring', deprecation.deprecate('/api/v2/monitoring'), monit
 app.get('/api/v2/monitoring', monitoring.getV2);
 app.get('/api/v1/impact', impact.v1.get);
 
+app.get('/api/v1/bulk-operations/:id', bulkOperations.v1.get);
+
 app.post('/api/v1/upgrade', jsonParser, upgrade.upgrade);
 app.post('/api/v1/upgrade/stage', jsonParser, upgrade.stage);
 app.post('/api/v1/upgrade/complete', jsonParser, upgrade.complete);
@@ -659,6 +663,7 @@ app.get('/api/v1/place', place.v1.getAll);
 app.get('/api/v1/place/:uuid', place.v1.get);
 app.postJson('/api/v1/place', place.v1.create);
 app.putJson('/api/v1/place/:uuid', place.v1.update);
+app.delete('/api/v1/place/:uuid', place.v1.delete);
 
 /**
  * @openapi
@@ -734,6 +739,7 @@ app.get('/api/v1/person', person.v1.getAll);
 app.get('/api/v1/person/:uuid', person.v1.get);
 app.postJson('/api/v1/person', person.v1.create);
 app.putJson('/api/v1/person/:uuid', person.v1.update);
+app.delete('/api/v1/person/:uuid', person.v1.delete);
 
 app.get('/api/v1/contact', contact.v1.getAll);
 app.get('/api/v1/contact/uuid', contact.v1.getUuids);
@@ -796,6 +802,13 @@ app.put(
   credentials.put
 );
 
+app.post(
+  '/api/v1/archive',
+  authorization.handleAuthErrors,
+  authorization.offlineUserFirewall,
+  archive.create
+);
+
 app.get('/api/v1/users-doc-count', replicationLimitLogController.get);
 app.get('/api/v1/replication-failure-logs', replicationFailureLogController.get);
 app.get('/api/v1/replication-health/failed', replicationHealthController.failed);