@burgan-tech/morph-touch-runtime 0.0.5 → 0.0.7

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

@@ -0,0 +1,742 @@
+# 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. 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).
+
+---
+
+## 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}`. 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.
+  - **MessagingGateway:** SMS and push notifications ([notification-sender](../Workflows/notification-sender.json)).
+
+### High-level relationships
+
+```mermaid
+flowchart LR
+  subgraph absence [absence-entry]
+    A1[complete]
+    A2[complete-with-transfer]
+  end
+  subgraph rez [rezervation]
+    R1[validating]
+    R2[appointment-form]
+    R3[active]
+    R4[in-meet]
+  end
+  subgraph transfer [rezervation-transfer]
+    T1[awaiting-assignment]
+  end
+  subgraph notify [notification-sender]
+    N1[pending to complete]
+  end
+  subgraph room [chat-room]
+    C1[permanent or reservation room]
+  end
+  R1 --> R2 --> R3
+  R3 --> N1
+  R3 --> absence
+  R3 --> R4
+  R4 --> room
+  A1 -->|start-transfer personal-leave| transfer
+  startChat[start-chat] --> room
+  resStart[rezervation-start] --> room
+  resStart --> R4
+```
+
+---
+
+## 2. absence-entry
+
+**File:** [Workflows/absence-entry.json](../Workflows/absence-entry.json)
+
+### Purpose
+
+- **Absence** records such as personal leave, customer meeting, etc.
+- **Public holiday** (`public-holiday`).
+- **Company working hours** and **advisor-specific working hours** (`working-hours-change` — with or without advisor for company-wide scope).
+
+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)).
+- When conditions hold, task `start-transfer-from-absence-entry` starts the **`rezervation-transfer`** subflow (`StartTransferFromAbsenceEntryMapping`).
+  - If **`endDateTime` is set**, transfer type is **annual leave** (`annual-leave`).
+  - If **`endDateTime` is empty**, type is **termination** (`termination`).
+  - Instance data must include **`advisor`**, **`advisorType`**, and **`startDateTime`**; otherwise the transfer task is skipped (`skipped` + reason).
+
+Final state: `complete-with-transfer` (transfer started).
+
+---
+
+## 3. rezervation-transfer
+
+**File:** [Workflows/rezervation-transfer.json](../Workflows/rezervation-transfer.json)
+
+### Purpose
+
+Move the source advisor’s appointments in a date range to suitable target advisors; run required Matrix operations on permanent chat rooms (per transfer vs update plan).
+
+### Initial tasks (summary)
+
+1. **Transfer type:** Without `endDate`, `termination` and a default far end date; with `endDate`, `annual-leave`.
+2. **Source appointments:** `get-rezervations`-style query (`FetchRezervationsForTransferMapping`).
+3. **Advisor list:** Active instances, workflow key resolution from `advisorType` / source id (`FetchAdvisorsForTransferMapping`).
+4. **Absence records:** Completed `public-holiday`, `working-hours-change`, `personal-leave` (`FetchAbsenceEntriesForTransferMapping`).
+5. **Enrichment:** All active appointments + slot validity (holiday, working hours, personal leave, conflicts) — `EnrichRezervationsForTransferMapping`.
+
+### Key checks
+
+- **`confirm-transfer`:** `validate-transfer-availability` — ensures the target advisor has no conflicting **active / in-meet** reservation in that slot; produces `validationResult.allValid` / `details`.
+- **`transferPlan`:** Postman example: each row has `rezervationKey` + `targetAdvisor` ([postman_collection.json](../../postman_collection.json) — “Confirm Transfer”).
+- Steps for permanent rooms using **`permanentRoomPlan`** (room `roomId` + `newAdvisorId`) are described in the collection notes.
+
+---
+
+## 4. rezervation
+
+**File:** [Workflows/rezervation.json](../Workflows/rezervation.json)
+
+### State outline
+
+`validating` → `appointment-form` or `slot-unavailable` → `active` → `in-meet` → `meet-completed`  
+Cancellations: `user-cancelled`, `advisor-cancelled`, `timeout`, etc.
+
+### Controls
+
+| Topic | Source | Description |
+|------|--------|-------------|
+| At most 2 reservations | `check-duplicate-rezervation` | For the same user, in certain confirmed states, at most **2** active reservations; **no overlapping** slots. |
+| Slot validity | `validate-slot-for-rezervation` | If the chosen range is missing from `get-available-slots` output → `slot-unavailable`; **`appointment-form-retry`** resubmits new date/time for re-validation. |
+| Date | `validate-date-for-rezervation` | Past or invalid dates are rejected. |
+| User | `set-user-from-headers-for-rezervation` | Request **`sub`** header is written to the instance. |
+| Confirm → active | `create-appointment` / confirmation chain | Order in workflow: previous advisor info, user info (`get-user-info-for-rezervation`), start **`notification-sender`**, create **`absence-entry`** (reservation record). |
+
+### Notification (when appointment is created)
+
+The `notification-sender` subflow starts during reservation confirmation. **Advisor** SMS/push body (summary):
+
+`Sayın " + (advisorName ?? "Danisman") + ", " + formattedDate + " tarihli randevunuz olusturulmustur."`
+
+**Customer** uses different copy (`SendSmsNotificationMapping` / `SendPushNotificationMapping` — [Workflows/src/SendSmsNotificationMapping.csx](../Workflows/src/SendSmsNotificationMapping.csx), [Workflows/src/SendPushNotificationMapping.csx](../Workflows/src/SendPushNotificationMapping.csx)). For channel selection and state transitions, see the **notification-sender** section (section 5 in this document).
+
+### Shared transitions
+
+- **`user-cancel` / `advisor-cancel` (active):** Triggers `cancel` on the related **`absence-entry`**; advisor cancel also sends a **cancellation notification**.
+- **`add-invited-participant`**, **`video-call-url-update`:** Merge invited-user list and video URL list.
+
+---
+
+## 5. notification-sender
+
+**File:** [Workflows/notification-sender.json](../Workflows/notification-sender.json)
+
+Subflow: started synchronously from reservation confirmation and other triggers. SMS (`/Messaging/sms/message/string`) and push (`/Messaging/push-notification/message`) calls are built in mappings against the `MessagingBaseUrl` secret.
+
+### States and automatic transitions
+
+| Source | Transition | Target | Condition (summary) |
+|--------|------------|--------|----------------------|
+| `pending` | `to-sms-sending` | `sms-sending` | `channels.sms == true` |
+| `pending` | `to-push-sending-from-pending` | `push-sending` | SMS not requested, `channels.push == true`, `hasRegisteredDevice == true` |
+| `pending` | `to-complete-from-pending` | `complete` | No applicable channel (push requested but no device, or no channel) |
+| `sms-sending` | (onEntry) | — | `send-sms-notification` task; `recipient.phone` (countryCode, prefix, number) required |
+| `sms-sending` | `to-push-sending-from-sms` | `push-sending` | `channels.push == true` and `hasRegisteredDevice == true` |
+| `sms-sending` | `to-complete-from-sms` | `complete` | Push not requested or no registered device |
+| `push-sending` | (onEntry) | — | `send-push-notification`; `recipient` uses `citizenshipNo` / `customerNo` |
+| `push-sending` | `to-complete-from-push` | `complete` | Always after push |
+
+**Copy:** `userType == "advisor"` uses advisor SMS/push text; `user` uses customer text (mapping summaries in the CSX files above).
+
+Postman: folder **Notification Sender Subprocess** — SMS only, push only, no channel, no device scenarios.
+
+---
+
+## 6. rezervation-start
+
+**File:** [Workflows/rezervation-start.json](../Workflows/rezervation-start.json)
+
+Both customer and advisor can start the meeting; the **first starter** takes the path that creates the reservation room; the other **joins**.
+
+### Requirements / checks
+
+- **`randevuKey`** required; state and data read via DAPR (`GetRezervationStateMapping`, `GetRezervationDataMapping`).
+- **Invited:** If `participantType == "invited"` and `invitedUserId` is not in the reservation `invitedUser` list → **`not-allowed`**.
+- If reservation state is not **`active`** or **`in-meet`** → **`meet-not-active`**.
+- **Time window (`check-randevu-time`):** Start allowed at most **15 minutes** before appointment start (script compares with `UtcNow + 3`); otherwise an error like `MEET_NOT_STARTED`.
+- **Invited and not yet in-meet:** `meet-not-started` branch.
+
+### Room and in-meet
+
+- If state is **`active`:** **`create-room-and-trigger`** — starts **`chat-room`** synchronously (`roomType: rezervation`), loads room data, fires **`to-in-meet`** on the main **`rezervation`**.
+- If state is already **`in-meet`:** **`join-room`** — Matrix `join`, `x-matrix-user` by participant type (user / advisor / invited).
+
+### End
+
+In `end` state, **`start-video-call`** subflow runs (LiveKit, etc.).
+
+---
+
+## 7. chat-room
+
+**File:** [Workflows/chat-room.json](../Workflows/chat-room.json)
+
+### Purpose
+
+- **Permanent room** (`roomType: permanent`): Matrix room keyed by user + advisor type + advisor.
+- **Reservation room** (`roomType: rezervation`): Process room tied to reservation key.
+
+### Behaviour summary
+
+- Creation: Matrix `createRoom`, invite, `join-user-to-room`.
+- **`activated`:** add member (`update`), remove member (`remove`), advisor **`transfer`** (kick + invite + join).
+- **`deactivate` / `activate`** states.
+- Second room creation blocked for same **user + advisorType + activated** on permanent rooms (`ALREADY_COMPLETED`).
+
+### Domain functions (via workflow)
+
+`get-chat-rooms`, `get-room-messages`, `send-room-message`, `get-matrix-sync` ([chat-room.json](../Workflows/chat-room.json) `attributes.functions`).
+
+---
+
+## 8. start-chat
+
+**File:** [Workflows/start-chat.json](../Workflows/start-chat.json)
+
+### Purpose
+
+Open permanent advisor chat: create room if missing, otherwise go straight to chat.
+
+### Flow
+
+1. **`check-existing-permanent-chat-room`:** Whether the user already has a permanent room for the same `advisorType`; `advisorId` match kept in a separate flag.
+2. **Existing room + same advisor** → **`in-chat`** (`open-existing-room`).
+3. **Existing room + different advisor** → **`to-change-advisor`:** fire **`transfer`** on `chat-room`, then **`in-chat`**.
+4. **No room** → **`start-permanent-chat-room`** starts **`chat-room`** synchronously, then **`in-chat`**.
+
+---
+
+## 9. add-participant-to-rezervation
+
+**File:** [Workflows/add-participant-to-rezervation.json](../Workflows/add-participant-to-rezervation.json)
+
+### Prerequisite
+
+Reservation state **`active`** or **`in-meet`**; otherwise **`state-not-valid`**.
+
+### Branches
+
+- **`in-meet`:** **update** on `chat-room` (new member) + **`add-invited-participant`** on `rezervation` + **`start-video-call`** subflow (invited customer path).
+- **`active`:** **`update-invited`** → **`end`** (invited update only).
+
+`newUserId` / `randevuKey` are required in task mappings.
+
+---
+
+## 10. Domain functions (summary)
+
+| Function | File | Purpose / notes |
+|----------|------|------------------|
+| `check-livekit-room-access` | [Functions/check-livekit-room-access.1.0.0.json](../Functions/check-livekit-room-access.1.0.0.json) | Query `access_token` (JWT or `prefix:roomName:participantName`). Participant validation on a single matching **active/in-meet** reservation; error on multiple matches. |
+| `get-absence-entry` | [Functions/get-absence-entry.1.0.0.json](../Functions/get-absence-entry.1.0.0.json) | Required `absenceType`: `public-holiday`, `personal-leave`, `working-hours-change`, `rezervation`. Optional `advisor`, `startDate`, `endDate`, `pageSize`. |
+| `get-advisor-stats` | [Functions/get-advisor-stats.1.0.0.json](../Functions/get-advisor-stats.1.0.0.json) | Advisor presence (Matrix: online, offline, busy, away). |
+| `get-available-slots` | [Functions/get-available-slots.1.0.0.json](../Functions/get-available-slots.1.0.0.json) | `advisorId`, `date`, optional `duration` (minutes). |
+| `get-chat-rooms` | [Functions/get-chat-rooms.1.0.0.json](../Functions/get-chat-rooms.1.0.0.json) | **`user` OR `advisor`** (mutually exclusive). |
+| `get-customer-info` | [Functions/get-customer-info.1.0.0.json](../Functions/get-customer-info.1.0.0.json) | Customer profile. |
+| `get-matrix-sync` | [Functions/get-matrix-sync.1.0.0.json](../Functions/get-matrix-sync.1.0.0.json) | Matrix sync payload. |
+| `get-rezervations` | [Functions/get-rezervations.1.0.0.json](../Functions/get-rezervations.1.0.0.json) | Filtered reservation list. |
+| `get-room-messages` | [Functions/get-room-messages.1.0.0.json](../Functions/get-room-messages.1.0.0.json) | Room messages. |
+| `send-room-message` | [Functions/send-room-message.1.0.0.json](../Functions/send-room-message.1.0.0.json) | Send message to Matrix. |
+
+See [Functions/get-room-messages.http](../Functions/get-room-messages.http) for detailed HTTP examples.
+
+---
+
+## 11. Postman collection
+
+**File:** [postman_collection.json](../../postman_collection.json) (workspace root)  
+**Collection name:** vNext Touch Domain
+
+### Shared variables (defaults)
+
+| Variable | Example value |
+|----------|----------------|
+| `baseUrl` | `http://localhost:4201` |
+| `apiVersion` | `1` |
+| `domain` | `morph-touch` |
+| `instanceKey` / `user` | `core.user.user-001` |
+| `advisor` / `advisorId` | `morph-touch.portfolio-manager.pm-001` |
+
+### Workflow API templates
+
+- **Start instance:**  
+  `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 {{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 {{baseUrl}}/morph-touch/workflows/{flowKey}/instances/{{instanceIdOrKey}}/transitions/{transitionKey}?sync=true`  
+  Same: **id** or **`key`**. Body is usually `{ "attributes": { ... } }`.
+
+### Sample requests (collection folders)
+
+| Folder / request | Method | Notes |
+|------------------|--------|-------|
+| **Reservation Workflow → Start Rezervation** | POST | `sub` header; body: `user`, `advisor`, `startDateTime`, `endDateTime`. |
+| **Confirm Selection** | PATCH | `transitions/confirm-selection` — slot validation step. |
+| **Appointment Form Retry** | PATCH | `appointment-form-retry` + new `startDateTime` / `endDateTime`. |
+| **Create Appointment** | PATCH | `create-appointment` → `active`. |
+| **Rezervation Start Workflow** | POST | `randevuKey`, `participantType` (advisor / customer / invited). |
+| **Chat Room Workflow** | POST / PATCH | Permanent PM/IA start; `update`, `remove`, `transfer`. |
+| **Start Chat Workflow** | POST | Creates permanent room if missing, else `in-chat`. |
+| **Rezervation Transfer** | POST + PATCH | `startDate`/`endDate`; `confirm-transfer` with `transferPlan`. |
+| **Get Absence Entry Function** | GET | `.../functions/get-absence-entry?absenceType=...` |
+| **Get Available Slots** | GET | `advisorId`, `date`, `duration`. |
+| **Get Chat Rooms** | GET | `user=...` or `advisor=...` |
+| **Matrix Synapse API** | various | `http://localhost:9080/...` — presence, createRoom (manual test). |
+| **Notification Sender Subprocess** | POST | `workflows/notification-sender/instances/start` — channel flags and recipient shape examples. |
+
+Collection descriptions reference [vNext documentation](https://github.com/burgan-tech/vnext-runtime/tree/main/doc/en) for instance filtering and task types.
+
+---
+
+## 12. Extra checks and edge cases
+
+- **Reservation cancel:** Triggers `absence-entry` cancel; on older instances without `absenceEntryKey`, cancel may no-op.
+- **Multiple invitees / video URLs:** List merge via `merge-invited-user`, `merge-video-call-urls`.
+- **check-livekit-room-access:** Token format JWT or `room:participant`; multiple matches yield an unusable result.
+- **notification-sender:** SMS requires phone structure; push uses `citizenshipNo` / `customerNo` and registered-device flag.
+- **chat-room:** Matrix `M_ROOM_IN_USE`; history visibility limited to allowed values (`shared`, `invited`, `joined`, `world_readable`) in mappings.
+
+---
+
+## 13. Related source files
+
+- Workflow JSON: [Workflows/](../Workflows/)
+- C# mappings: [Workflows/src/](../Workflows/src/)
+- Function definitions: [Functions/](../Functions/)
+- Project rules: [.cursorrules](../../.cursorrules)
+
+---
+
+## 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>`:** The access token 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.*