@onereach/types-hitl-api 1.0.5-rc.0 → 1.0.5-rc.5

package/README.md

@@ -1,35 +1,35 @@
-## Getting Started
+# HitL API
 
-In this section we are going to explain how to run the application locally, without (almost) any OneReach dependencies.
+Backend API for Human in the Loop. This service handles session, agent, migration, task, and browser-facing API behavior used by the `hitl` frontend and related platform integrations.
 
-#### Make sure OneReach NPM token is available
+## Local Development
 
-In order to install some dependencies you are going to need a valid token available as a variable - `OR_NPM_TOKEN`. If it is not available using `echo $OR_NPM_TOKEN` - you should ask someone to help you setup access to OneReach NPM.
+Requirements:
 
-#### Installing local PostgreSQL
+- Node.js 20+
+- npm 10+
+- Docker Desktop or another local PostgreSQL setup
+- `OR_NPM_TOKEN` for private dependencies
+- deploy-platform installed locally so config can be generated
 
-If you already have a local PostgreSQL installed, or know how to do so - you are free to go to the next section.
+### 1. Install dependencies
 
-The easiest way to install a local database - is by using **Docker** - [Install Docker Desktop](https://www.docker.com/products/docker-desktop). After making sure **Docker** is installed and is available through command line as `docker` - we can proceed with installing and creating a local database.
+```bash
+npm install
+```
 
-Run the following commands (and replace `mysecretpassword` here and in the examples below with an actual password):
+### 2. Start PostgreSQL
 
-```
+Example with Docker:
+
+```bash
 docker pull postgres
 docker run --name postgresql-local -e POSTGRES_USER=hitl-app -e POSTGRES_PASSWORD=mysecretpassword -e POSTGRES_DB=hitl-app-db -p 5432:5432 -d postgres
 ```
 
-You should be able to connect to this database using command (enter the password, if it is asked):
-
-```
-docker exec -it postgresql-local psql hitl-app-db -U hitl-app -W
-```
-
-#### Connecting to the local database
+### 3. Create `.env`
 
-Create a file named `.env` in the project root directory with the following content:
-
-```
+```conf
 APP_DEV_PORT=8080
 DB_USER=hitl-app
 DB_PASSWORD=mysecretpassword
@@ -39,49 +39,46 @@ DB_NAME=hitl-app-db
 SCHEDULED_TASKS_SWITCH='{"ARCHIVE_SESSION_EVENTS":true,"CLEAN_UP_LISTENERS":true,"CLEAN_UP_SESSIONS":true,"ADD_EVENTS_TO_ARCHIVE":true,"ADD_MEMBERS_TO_ARCHIVE":true,"CLEAN_UP_CONTACTLESS_SESSIONS":true,"FIX_EXPIRED_AGENT_STATUSES":true,"DELETE_EXPIRED_SESSIONS":true,"LONG_EXPIRE_DAYS":7,"SHORT_EXPIRE_DAYS":1}'
 ```
 
-You can change all the values above, if you want to, just make sure that the variables in `.env` file point to some valid PostgreSQL instance.
-
-#### Retrieving deploy config
-
-Make sure you have `deploy-platform` project installed on your machine, and a command `or` is globally available.
+### 4. Generate deploy config
 
-Run the following commands:
-
-```
+```bash
 or get-config --branch local --client development --env qa --feature master --project hitl-api --service hitl_api.config --service-or-eval service > config.json
 ```
 
-A file `config.json`, which is ignored by git, should appear in the project root with some content.
-
-#### Installing packages and starting the application
+### 5. Start the server
 
-After installing third party dependencies, we can finally run:
-
-```
-npm install
+```bash
 npm start
 ```
 
-This will start the application in the development mode as a simple `express` server. Changes to the code will be tracked and server will restart automatically.
-
-An almost empty `config.json` file is required to build the application. In order to run the application on AWS, we are going to need real env variables that we are going to retrieve later.
+### 6. Run migrations
 
-Server now is ready to accept requests, but it will probably fail on every attempt to access database. In order to read and write from database we need to send a request to create or update our SQL tables.
+```bash
+curl --location --request POST 'http://localhost:8080/api/v1/migrations' --header 'Authorization: user'
+```
 
-In order to run all migrations to the latest version, run the following request in the console (or in Postman):
+### 7. Run tests
 
-```
-curl --location --request POST 'http://localhost:8080/api/v1/migrations' --header 'Authorization: user'
+```bash
+npm test
 ```
 
-After successful response you should be able to send all other requests.
+## Main Areas
 
-#### Testings the application
+- `src/api/` and `src/api-express/`: serverless and express entrypoints
+- `src/api-common/`: shared middleware, auth, logging, validation, and versions endpoints
+- `src/api-express/migrations/`: SQL and migration management
+- `tests/`: Jest-based backend coverage
 
-In order to verify that (most of) the application logic works, you should run:
+## Shared Parent Domain Aliases
 
-```
-npm test
-```
+`hitl-api` participates in the shared-parent-domain alias flow as a supporting API for branded `hitl` deployments.
+
+That means:
+
+- browser-facing host trust should be explicit
+- CORS behavior should be driven by configured trusted hosts
+- deploy-platform config must stay aligned with the UI aliases and allowed hosts used by the frontend
 
-If all tests pass successfully - congratulations, this means that the local deployment was successful.
+Read the full platform behavior here:
+[deploy-platform shared-parent-domain alias documentation](https://gitlab.internal.onereach.io/onereach/platform/deploy-platform/docs/shared-parent-domain-aliases.md)

package/dist/types/interfaces/api/listeners.d.ts

@@ -8,6 +8,7 @@ export interface IListener extends ITimestamps {
     readonly type: CALLBACK_TYPE;
     readonly userId: string;
     readonly version: string;
+    readonly meta?: any;
 }
 /** Implicitly inherits ChannelTarget interface from Orbes */
 export interface IListenerCallback {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onereach/types-hitl-api",
-  "version": "1.0.5-rc.0",
+  "version": "1.0.5-rc.5",
   "author": "OneReach.ai",
   "main": "dist/types/index.types.js",
   "types": "dist/types/index.types.d.ts",