@burgan-tech/morph-touch-runtime 0.0.6 → 0.0.8

package/morph-touch/doc/morph-touch-domain.en.md

@@ -1,6 +1,6 @@
 # Morph-touch domain — technical overview
 
-This document summarizes appointment (rezervation), absence, chat room, notification, and transfer flows in the `morph-touch` domain, based on workflow definitions and task mapping behaviour. API examples align with the [postman_collection.json](../../postman_collection.json) collection.
+This document summarizes appointment (rezervation), absence, chat room, notification, and transfer flows in the `morph-touch` domain, based on workflow definitions and task mapping behaviour. HTTP examples use the **`{{BaseUrl}}/morph-touch/...`** template; the [postman_collection.json](../../postman_collection.json) collection may still use variables such as `api/v{{apiVersion}}` — align `baseUrl` and path prefixes with your gateway.
 
 Turkish version: [morph-touch-domain.md](morph-touch-domain.md).
 
@@ -9,7 +9,7 @@ Turkish version: [morph-touch-domain.md](morph-touch-domain.md).
 ## 1. Overview and terminology
 
 - **Domain:** `morph-touch`
-- **Workflow instance:** vNext instance model with `key`, `flow` (`sys-flows`), `domain`, and `version`; started over HTTP at `.../workflows/{flowKey}/instances/...`, transitions at `.../transitions/{transitionKey}`.
+- **Workflow instance:** vNext instance model with `key`, `flow` (`sys-flows`), `domain`, and `version`; started over HTTP at `.../workflows/{flowKey}/instances/...`, transitions at `.../transitions/{transitionKey}`. After `instances/`, the path may use the platform **instance id** (UUID) or the instance **`key`** from the `start` request.
 - **Integrations:**
   - **DAPR / application API:** `api/v{version}/{domain}/...` (paths such as `functions/state`, `functions/data` in mappings).
   - **Matrix:** `MatrixBaseUrl` (secret); room creation, join, invite, kick, history visibility.
@@ -63,6 +63,8 @@ flowchart LR
 
 Records are usually kept in `complete`; updated via `update`, moved to `cancelled` via `cancel`.
 
+For detailed request bodies, key rules, and cURL examples, see **section 14**.
+
 ### Link to appointment transfer
 
 - Transition **`start-transfer`** is evaluated only when `absenceType == "personal-leave"` (`CanStartTransferMapping` — [Workflows/src/CanStartTransferMapping.csx](../Workflows/src/CanStartTransferMapping.csx)).
@@ -276,13 +278,14 @@ See [Functions/get-room-messages.http](../Functions/get-room-messages.http) for
 ### Workflow API templates
 
 - **Start instance:**  
-  `POST {{baseUrl}}/api/v{{apiVersion}}/{{domain}}/workflows/{flowKey}/instances/start?sync=true`  
+  `POST {{baseUrl}}/morph-touch/workflows/{flowKey}/instances/start?sync=true`  
   Examples: `rezervation`, `absence-entry`, `rezervation-start`, `chat-room`, `start-chat`, `rezervation-transfer`, `notification-sender` (subflow).
 - **Get instance:**  
-  `GET .../workflows/{flowKey}/instances/{{instanceId}}`
+  `GET {{baseUrl}}/morph-touch/workflows/{flowKey}/instances/{{instanceIdOrKey}}`  
+  Path segment: platform **instance `id`** (UUID) or the instance **`key`** from the `start` request (e.g. `working-hour`, `rez-...`).
 - **Transition:**  
-  `PATCH .../workflows/{flowKey}/instances/{{instanceId}}/transitions/{transitionKey}?sync=true`  
-  Body is usually `{ "attributes": { ... } }`.
+  `PATCH {{baseUrl}}/morph-touch/workflows/{flowKey}/instances/{{instanceIdOrKey}}/transitions/{transitionKey}?sync=true`  
+  Same: **id** or **`key`**. Body is usually `{ "attributes": { ... } }`.
 
 ### Sample requests (collection folders)
 
@@ -325,4 +328,415 @@ Collection descriptions reference [vNext documentation](https://github.com/burga
 
 ---
 
+## 14. API usage guide (cURL and field rules)
+
+### 14.1 Prerequisite order
+
+For appointments and **get-available-slots**, define **company working hours** first (`absenceType: working-hours-change`, instance `key: "working-hour"`, tags `working-hours-change` + `company`). Then use public holidays, advisor leave / custom hours, and the reservation flow.
+
+### 14.2 `{{BaseUrl}}`, path template, and authentication
+
+- In all examples, **`{{BaseUrl}}`** is your API gateway **root** (e.g. `https://<host>` or `https://<host>/ebanking` depending on deployment). Set it per APISIX / environment docs; avoid a trailing slash on the root or you may get **double slashes** (`//morph-touch`) when concatenating.
+- Standard template: **`{{BaseUrl}}/morph-touch/workflows/...`** and **`{{BaseUrl}}/morph-touch/functions/...`** (e.g. `{{BaseUrl}}/morph-touch/workflows/absence-entry/instances/start?sync=true`).
+- This matches the role of Postman’s `{{baseUrl}}`; this doc uses the name **`{{BaseUrl}}`**.
+- **`Authorization: Bearer <access_token>`:** In many setups this header is **required**; whether it is mandatory can **vary by environment** (e.g. local dev may omit it per policy). The access token itself is **environment-specific** (dev, test, production). Obtain it from your identity provider or whatever process your environment documents (APISIX, API portal, security team). `<access_token>` in examples is only a placeholder; never commit real tokens to the repo or shared docs.
+- In `.../workflows/{flowKey}/instances/<segment>/...`, `<segment>` is **`{{instanceIdOrKey}}`**: either the platform **instance id** or the instance **`key`**.
+
+### 14.3 Company working hours — `absence-entry` start (once)
+
+`key` must be **`working-hour`**. `absenceType` is **`working-hours-change`**. Under `customWorkingHours`, weekdays (`monday` … `sunday`) are arrays of `{ "start": "HH:mm", "end": "HH:mm" }`.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/absence-entry/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "working-hour",
+  "tags": ["working-hours-change", "company"],
+  "attributes": {
+    "absenceType": "working-hours-change",
+    "title": "Company working hours",
+    "customWorkingHours": {
+      "monday": [{"start": "09:00", "end": "12:00"}, {"start": "13:30", "end": "18:00"}],
+      "tuesday": [{"start": "09:00", "end": "12:00"}, {"start": "13:30", "end": "18:00"}],
+      "wednesday": [{"start": "09:00", "end": "12:00"}, {"start": "13:30", "end": "18:00"}],
+      "thursday": [{"start": "09:00", "end": "12:00"}, {"start": "13:30", "end": "18:00"}],
+      "friday": [{"start": "09:00", "end": "12:00"}, {"start": "13:30", "end": "17:00"}],
+      "saturday": [],
+      "sunday": []
+    }
+  }
+}'
+```
+
+### 14.4 Company working hours — later updates (`update`)
+
+Usually **one** `start` for company-wide record; afterwards use only **`PATCH .../transitions/update`**. In the URL, **`{{instanceIdOrKey}}`** may be the **platform instance id** (UUID) from the response or the fixed company **`key`** (`working-hour`).
+
+```bash
+curl --location --request PATCH '{{BaseUrl}}/morph-touch/workflows/absence-entry/instances/{{instanceIdOrKey}}/transitions/update?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "attributes": {
+    "title": "Company working hours (updated)",
+    "customWorkingHours": {
+      "monday": [{"start": "08:30", "end": "12:00"}, {"start": "13:00", "end": "17:30"}],
+      "tuesday": [{"start": "08:30", "end": "12:00"}, {"start": "13:00", "end": "17:30"}],
+      "wednesday": [{"start": "08:30", "end": "12:00"}, {"start": "13:00", "end": "17:30"}],
+      "thursday": [{"start": "08:30", "end": "12:00"}, {"start": "13:00", "end": "17:30"}],
+      "friday": [{"start": "08:30", "end": "12:00"}, {"start": "13:00", "end": "16:30"}],
+      "saturday": [],
+      "sunday": []
+    }
+  }
+}'
+```
+
+### 14.5 Public holiday (`public-holiday`)
+
+Key pattern: `public-holiday-{date}`. `absenceType` **`public-holiday`**. Set `startDateTime` / `endDateTime` for full or half day.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/absence-entry/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "public-holiday-2026-04-23",
+  "tags": ["public-holiday"],
+  "attributes": {
+    "absenceType": "public-holiday",
+    "startDateTime": "2026-04-23T00:00:00",
+    "endDateTime": "2026-04-23T23:59:59",
+    "title": "National Sovereignty and Children's Day"
+  }
+}'
+```
+
+### 14.6 Personal leave (`personal-leave`)
+
+Key pattern: `personal-leave-{advisorId}-{startDateTime}-{endDateTime}`. `absenceType` **`personal-leave`**. `advisor` is the advisor unique id (often employee id). `advisorType` may be short (**`PM` / `IA`**) or full workflow values (**`portfolio-manager` / `investment-advisor`**) per your contract.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/absence-entry/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'sub: <user_sub>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "personal-leave-<advisorId>-2026-04-07T00:00:00-2026-04-07T12:59:59",
+  "tags": ["personal-leave"],
+  "attributes": {
+    "advisor": "<advisorId>",
+    "advisorType": "PM",
+    "absenceType": "personal-leave",
+    "startDateTime": "2026-04-07T00:00:00",
+    "endDateTime": "2026-04-07T12:59:59",
+    "title": "Customer meeting"
+  }
+}'
+```
+
+### 14.7 Advisor-specific working hours (`working-hours-change` + advisor)
+
+Key pattern: `working-hour-{advisorId}`. Tags: `working-hours-change`, `advisor`. `advisor` required; `customWorkingHours` same shape as §14.3.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/absence-entry/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "working-hour-<advisorId>",
+  "tags": ["working-hours-change", "advisor"],
+  "attributes": {
+    "advisor": "<advisorId>",
+    "absenceType": "working-hours-change",
+    "title": "Advisor custom hours",
+    "customWorkingHours": {
+      "monday": [{"start": "10:00", "end": "12:00"}, {"start": "13:00", "end": "19:00"}],
+      "tuesday": [],
+      "wednesday": [],
+      "thursday": [],
+      "friday": [],
+      "saturday": [],
+      "sunday": []
+    }
+  }
+}'
+```
+
+### 14.8 Cancel — `cancel` transition
+
+```bash
+curl --location --request PATCH '{{BaseUrl}}/morph-touch/workflows/absence-entry/instances/{{instanceIdOrKey}}/transitions/cancel?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{"attributes": {}}'
+```
+
+### 14.9 Absence update — `update` (example: leave times)
+
+```bash
+curl --location --request PATCH '{{BaseUrl}}/morph-touch/workflows/absence-entry/instances/{{instanceIdOrKey}}/transitions/update?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "attributes": {
+    "startDateTime": "2026-01-28T15:00:00",
+    "endDateTime": "2026-01-28T17:00:00",
+    "title": "Customer meeting (updated)"
+  }
+}'
+```
+
+### 14.10 `get-absence-entry` function
+
+Required `absenceType`. Company-only: `working-hours-change` alone. Date range for public holidays; `advisor` for advisor working hours.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/functions/get-absence-entry?absenceType=working-hours-change' \
+  --header 'Accept: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>'
+
+curl --location '{{BaseUrl}}/morph-touch/functions/get-absence-entry?absenceType=public-holiday&startDate=2026-04-01T00:00:00&endDate=2026-04-30T23:59:59' \
+  --header 'Accept: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>'
+
+curl --location '{{BaseUrl}}/morph-touch/functions/get-absence-entry?absenceType=working-hours-change&advisor=<advisorId>' \
+  --header 'Accept: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>'
+```
+
+### 14.11 `get-available-slots`
+
+Returns free slots for `advisorId` on `date`; optional `duration` (minutes).
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/functions/get-available-slots?advisorId=<advisorId>&date=2026-03-17' \
+  --header 'Accept: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>'
+```
+
+Example body:
+
+```json
+{
+  "getAvailableSlots": {
+    "availableSlots": [
+      "09:00-09:30",
+      "09:30-10:00",
+      "10:00-10:30"
+    ]
+  }
+}
+```
+
+### 14.12 Reservation flow (`rezervation`)
+
+1. **`start`:** `key` must be unique per reservation; reuse as `randevuKey`. Align `startDateTime` / `endDateTime` with slots. Send **`sub`** (customer identity).
+2. Past date or duplicate active reservation rules may reject creation (see §4 / §12).
+3. If state is **`slot-unavailable`**, call **`appointment-form-retry`** with new times.
+4. After **`appointment-form`**, **`confirm-selection`** confirms user input.
+5. **`create-appointment`** moves to **`active`**; notifications and `get-user-info-for-rezervation` run; SMS to registered phone.
+
+In the transition URLs below, use either the **platform instance id** or the reservation **`key`** from `start` (e.g. `rez-<unique-suffix>`) as `{{rezervationInstanceIdOrKey}}`.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/rezervation/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'sub: <customer_sub>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "rez-<unique-suffix>",
+  "tags": ["appointment", "randevu"],
+  "attributes": {
+    "user": "<userRef>",
+    "advisor": "<advisorRef>",
+    "startDateTime": "2026-04-17T10:30:00",
+    "endDateTime": "2026-04-17T11:00:00"
+  }
+}'
+```
+
+```bash
+curl --location --request PATCH '{{BaseUrl}}/morph-touch/workflows/rezervation/instances/{{rezervationInstanceIdOrKey}}/transitions/appointment-form-retry?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "attributes": {
+    "startDateTime": "2026-04-17T11:00:00",
+    "endDateTime": "2026-04-17T11:30:00"
+  }
+}'
+```
+
+```bash
+curl --location --request PATCH '{{BaseUrl}}/morph-touch/workflows/rezervation/instances/{{rezervationInstanceIdOrKey}}/transitions/confirm-selection?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{"attributes": {}}'
+```
+
+```bash
+curl --location --request PATCH '{{BaseUrl}}/morph-touch/workflows/rezervation/instances/{{rezervationInstanceIdOrKey}}/transitions/create-appointment?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{"attributes": {}}'
+```
+
+### 14.13 Start meeting (`rezervation-start`)
+
+Callable up to **15 minutes** before start; earlier yields **`meet-not-started`**. `randevuKey` is the reservation `key`. `participantType`: `customer`, `advisor`, or `invited`. For **`invited`**, send **`invitedUserId`** and add the user via **add-participant-to-rezervation** first. First participant creates the Matrix room and moves reservation to **`in-meet`**; second joins.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/rezervation-start/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "randevu-<unique-suffix>",
+  "tags": ["randevu", "meeting"],
+  "attributes": {
+    "randevuKey": "rez-<unique-suffix>",
+    "participantType": "advisor"
+  }
+}'
+```
+
+For invited: set `participantType: "invited"` and `invitedUserId: "<inviteeId>"`.
+
+### 14.14 Add participant (`add-participant-to-rezervation`)
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/add-participant-to-rezervation/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "add-participant-<unique-suffix>",
+  "tags": ["rezervation", "add-participant"],
+  "attributes": {
+    "randevuKey": "rez-<unique-suffix>",
+    "newUserId": "<inviteeEmployeeId>"
+  }
+}'
+```
+
+Suggested `key` pattern: `add-participant-{advisorId}-{randevuKey}`.
+
+### 14.15 Active reservation update (`rezervation-update`)
+
+`randevuKey` is the reservation `key`. Send `startDateTime`, `endDateTime`, and/or `advisor` as needed. With **`autoProcess: true`** the flow may auto-validate; with **`false`**, after `start` send updates via **`PATCH .../transitions/to-validate`** ([rezervation-update.json](../Workflows/rezervation-update.json)).
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/rezervation-update/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "rezervation-update-<unique-suffix>",
+  "tags": ["rezervation", "randevu", "update"],
+  "attributes": {
+    "randevuKey": "rez-<unique-suffix>",
+    "startDateTime": "2026-02-03T10:00:00",
+    "endDateTime": "2026-02-03T10:30:00",
+    "advisor": "<newAdvisorRef>",
+    "autoProcess": true
+  }
+}'
+```
+
+### 14.16 Permanent chat — `start-chat`
+
+Creates room if missing; otherwise **`in-chat`**. `user` is the customer; `advisorType` **`PM`** or **`IA`**; `advisorId` unique advisor id.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/workflows/start-chat/instances/start?sync=true' \
+  --header 'Content-Type: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>' \
+  --data '{
+  "key": "start-chat-<unique-suffix>",
+  "tags": ["chat", "start-chat"],
+  "attributes": {
+    "user": "<userRef>",
+    "advisorType": "IA",
+    "advisorId": "<advisorId>"
+  }
+}'
+```
+
+### 14.17 Chat rooms and messages (domain functions)
+
+Canonical paths: **`GET {{BaseUrl}}/morph-touch/functions/get-chat-rooms`** and **`GET .../functions/get-room-messages`**. Some gateways may use a different prefix.
+
+**`get-chat-rooms`:** `user` **or** `advisor` (not both). Optional `roomType`: `permanent` or `rezervation`.
+
+**Note:** [GetChatRoomsMapping](../Functions/src/GetChatRoomsMapping.csx) may query instances with a fixed internal `pageSize=100`; a query `pageSize` parameter may not always apply.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/functions/get-chat-rooms?user=<userRef>&roomType=permanent' \
+  --header 'Accept: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>'
+```
+
+**`get-room-messages`:** Required `roomId`, `user`. Optional **`limit`** (default 50 in mapping); optional `from` for pagination.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/functions/get-room-messages?roomId=<encodedRoomId>&user=<userRef>&limit=20' \
+  --header 'Accept: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>'
+```
+
+### 14.18 Reservation list — `get-rezervations`
+
+Query: `advisorId`, `userId`, `startDate`, `endDate` — dates optional; filter a range when set.
+
+```bash
+curl --location '{{BaseUrl}}/morph-touch/functions/get-rezervations?advisorId=<advisorId>&startDate=2026-02-01&endDate=2026-02-28' \
+  --header 'Accept: application/json' \
+  --header 'Accept-Language: tr-TR' \
+  --header 'X-Request-Id: <uuid>' \
+  --header 'Authorization: Bearer <access_token>'
+```
+
+---
+
 *This document is derived from code and workflow definitions; runtime URLs and auth may vary by environment.*