cht_usr - Getting ready for go-live. Large pull request over XMas bre…

…ak (#607)

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.env*
+src/package.json

Dockerfile

@@ -0,0 +1,19 @@
+FROM node:20-alpine
+
+ENV EXTERNAL_PORT 3000
+ENV PORT 3000
+ENV NODE_ENV production
+
+WORKDIR /app
+
+HEALTHCHECK --interval=30s --timeout=3s \
+  CMD curl -f http://localhost:${PORT}/_healthz || exit 1
+
+COPY package*.json .
+RUN npm ci --omit=dev
+
+COPY src ./src
+COPY tsconfig.json .
+RUN npm run build
+
+CMD npm start

README.md

@@ -1,16 +1,83 @@
-# cht-usr
+# CHT User Management Tool
 
-### Goal
+## Goal
 
-Build a small user-facing web app using [CHT's API](https://docs.communityhealthtoolkit.org/apps/reference/api/) that supports the current user management workflows
+A simple user-facing web application using [CHT's API](https://docs.communityhealthtoolkit.org/apps/reference/api/) that supports user management needs for CHT projects at scale.
 
-1. https://docs.communityhealthtoolkit.org/apps/guides/data/csv-to-docs/
-2. https://docs.communityhealthtoolkit.org/apps/guides/data/users-bulk-load/
+## Using this tool with your CHT Project
 
-Currently an MVP, everything is cached in memory so do not use this for anything other than test environments.
+To use the User Management Tool with your CHT project, you'll need to create a new project configuration folder and follow some deployment steps.
 
-### Configuration file
+### Configuration
 
-#### Forms properties
+1. Create a new folder in `src/config`.
+2. Create a `config.json` file and specify the values as defined below.
+3. Add reference to your configuration folder in `src/config/config-factory.ts`.
 
-| Property | Description |
+Property | Type | Description
+-- | -- | --
+`domains` | Array | Controls the list of instances which the user can login to
+`domains.friendly` | string | Friendly name for the instance (eg. "Migori")
+`domains.domain` | string | Hostname for the instance (eg. "migori-echis.health.go.ke")
+`domains.useHttp` | boolean | Whether to make an insecure connection (http) to the hostname (defaults to false)
+`contact_types` | Array | One element for each type of user which can be created by the system
+`contact_types.name` | string | The name of the contact_type as it [appears in the app's base_settings.json](https://docs.communityhealthtoolkit.org/apps/reference/app-settings/hierarchy/)
+`contact_types.friendly` | string | Friendly name of the contact type
+`contact_types.contact_type` | string | The contact_type of the primary contact. [As defined in base_settings.json](https://docs.communityhealthtoolkit.org/apps/reference/app-settings/hierarchy/)
+`contact_types.user_role` | string | The [role](https://docs.communityhealthtoolkit.org/apps/reference/app-settings/user-roles/) of the user which is created
+`contact_types.username_from_place` | boolean | When true, the username is generated from the place's name. When false, the username is generated from the primary contact's name. Default is false.
+`contact_types.hierarchy` | Array<ConfigProperty> | Defines how this `contact_type` is connected into the hierarchy. An element with `level:1` (parent) is required and additional elements can be provided to support disambiguation. See [ConfigProperty](#ConfigProperty).
+`contact_types.hierarchy.level` | integer | The hierarchy element with `level:1` is the parent, `level:3` is the great grandparent. 
+`contact_types.replacement_property` | Property | Defines how this `contact_type` is described when being replaced. The `property_name` is always `replacement`. See [ConfigProperty](#ConfigProperty).
+`contact_types.place_properties` | Array<ConfigProperty> | Defines the attributes which are collected and set on the user's created place. See [ConfigProperty](#ConfigProperty).
+`contact_types.contact_properties` | Array<ConfigProperty> | Defines the attributes which are collected and set on the user's primary contact doc. See [ConfigProperty](#ConfigProperty).
+`logoBase64` | Image in base64 | Logo image for your project
+
+#### ConfigProperty
+The `ConfigProperty` is a data structure used several times each `config.json` file. At a high level, a `ConfigProperty` defines a property on an object.
+
+Property | Type | Description
+-- | -- | --
+friendly_name | string | Defines how this data will be labeled in CSV files and throughout the user experience.
+property_name | string | Defines how the value will be stored on the object.
+type | ConfigPropertyType | Defines the validation rules, and auto-formatting rules. See [ConfigPropertyType](#ConfigPropertyType).
+parameter | any | See [ConfigPropertyType](#ConfigPropertyType).
+required | boolean | True if the object should not exist without this information.
+
+#### ConfigPropertyType
+The `ConfigPropertyType` defines a property's validation rules and auto-formatting rules. The optional `parameter` information alters the behavior of the `ConfigPropertyType`.
+
+Type | Validation Rules | Auto Formatting Rules | Validator | parameter
+-- | -- | -- | --
+string | Must be defined | Removes double whitespaces, leading or trailing whitespaces, and any character which is not alphanumeric or ` ()\-'` | None
+name | Must be defined | Same as string + title case + `parameter` behavior | One or more regexes which are removed from the value when matched (eg. `"parameter": ["\\sCHU"]` will format `This Unit` into `This`)
+regex | Must match the `regex` captured by `parameter` | Same as `string` | A regex which must be matched to pass validation (eg. `"parameter": "^\\d{6}$"` will accept only 6 digit numbers)
+phone | A valid phone number for the specified locality | Auto formatting provided by [libphonenumber](https://github.com/google/libphonenumber) | Two letter country code specifying the locality of phone number (eg. `"parameter": "KE"`)
+none | None | None | None
+gender | A binary gender (eg. `Male`, `Woman`, `M`) | Formats to either `Male` or `Female` | None
+
+### Deployment
+This tool is available via Docker by running `docker compose up`. Set the [Environment Variables](#environment-variables).
+
+## Development
+Create a `.env` file. Check out the `env.example` to get started. See [Environment Variables](#environment-variables).
+
+Then run 
+
+```
+npm run dev
+```
+
+or 
+
+```
+npm run build
+npm start
+```
+
+## Environment Variables
+Variable | Description
+-- | --
+CONFIG_NAME | Name of the configuration to use (eg. "CHIS-KE")
+PORT | Port to use when starting the web server
+COOKIE_PRIVATE_KEY | A string used to two-way encryption of cookies. Production values whould be a secret.

docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.7'
+
+services:
+  cht-user-management:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      - EXTERNAL_PORT=${EXTERNAL_PORT:-3000}
+      - COOKIE_PRIVATE_KEY=${COOKIE_PRIVATE_KEY}
+      - CONFIG_NAME=${CONFIG_NAME}
+    container_name: cht-user-management
+    ports:
+      - '${EXTERNAL_PORT}:${PORT:-3000}'
+    restart: always
+    command: npm start

env.example

@@ -1,4 +1,4 @@
-CHT_USER=
-CHT_PASSWORD=
-CHT_DOMAIN=
-COOKIE_PRIVATE_KEY=something special
+COOKIE_PRIVATE_KEY=
+CONFIG_NAME=chis-ke
+PORT=3000             # for development environment
+EXTERNAL_PORT=3555    # for docker

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "cht-usr",
+  "name": "cht-user-management",
   "version": "1.0.0",
   "main": "dist/index.js",
   "dependencies": {
@@ -12,6 +12,7 @@
     "@types/jsonwebtoken": "^9.0.5",
     "@types/lodash": "^4.14.201",
     "@types/node": "^20.8.8",
+    "@types/uuid": "^9.0.6",
     "axios": "^1.5.1",
     "csv": "^6.3.5",
     "dotenv": "^16.3.1",
@@ -30,28 +31,29 @@
     "@types/mocha": "^10.0.6",
     "@types/rewire": "^2.5.30",
     "@types/sinon": "^17.0.2",
-    "@types/uuid": "^9.0.6",
     "chai": "^4.3.10",
+    "chai-as-promised": "^7.1.1",
     "mocha": "^10.2.0",
     "rewire": "^7.0.0",
     "sinon": "^17.0.1",
     "ts-mocha": "^10.0.0",
     "tsc-watch": "^6.0.4"
   },
   "scripts": {
+    "cp-package-json": "cp package.json ./src",
     "test": "npx ts-mocha test/{,**}/*.spec.ts",
-    "build": "tsc",
+    "build": "npm run cp-package-json && npx tsc",
     "start": "node dist/index.js",
     "dev": "tsc-watch --onSuccess \"node dist/index.js\""
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/freddieptf/cht-usr.git"
+    "url": "git+https://github.com/medic/cht-user-management.git"
   },
   "author": "",
   "license": "ISC",
   "bugs": {
-    "url": "https://github.com/freddieptf/cht-usr/issues"
+    "url": "https://github.com/medic/cht-user-management/issues"
   },
-  "homepage": "https://github.com/freddieptf/cht-usr#readme"
+  "homepage": "https://github.com/medic/cht-user-management#readme"
 }