feat: add readme

pages/api/book-tickets/README.md

@@ -0,0 +1,112 @@
+# Webhooks used in **Book tickets** brain template
+
+For general information about using webhooks in Moveo you can check our [documentation](https://docs.moveo.ai/docs/get_started/webhooks)
+
+`get-events` [/api/book-tickets/get-events](#route-1-apibook-ticketsget-events)
+
+`get-event-dates` [/api/book-tickets/get-event-dates](#route-2-apibook-ticketsget-event-dates)
+
+`calculate-total-cost` [/api/book-tickets/calculate-total-cost](#route-3-apibook-ticketscalculate-total-cost)
+
+## Route 1: /api/book-tickets/get-events
+
+This is a POST endpoint that you can call like this:
+
+```sh
+curl -X POST -H "Content-Type: application/json" -H "X-Signature: <YOUR_SIGNATURE>" -d '{ "lang": "en", "context": {"event_type_value": "Movies", "area": "Athens"}}' "https://integration-guides.moveo.ai/api/book-tickets/get-events"
+```
+
+It returns a **carousel** with available events for a _category_ and _area_.
+
+### Quick overview of the code:
+
+1. Validate request
+2. Extract context variables from the request body
+3. Check for missing parameters
+4. Extract page. When `page_number` is negative we return a [text response]().
+5. Get the data from dummy endpoint
+6. Create and return a carousel using the data
+
+### Parameters (context variables)
+
+| Name             | Required | Type   | Description                                                                                                                                                                |
+| ---------------- | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| event_type_value | required | string | The type of the events. <br /> <br /> Supported values: `Concerts`, `Festivals`, `Theatrical performances`, `Musical shows`, `Dance performances`, `Kids movies`, `Movies` |
+| area             | required | string | The area where the events will be held. <br /> <br /> Supported values: `Athens`, `Thessaloniki`                                                                           |
+| page_number      | optional | number | An integer that is used for pagination. Negative value indicates the end of the results.                                                                                   |
+
+### Responses
+
+There are 4 possible scenarios of the webhook completing successfully:
+
+1. The `page_number` is missing from the context (should be the first time the webhook is called) and the search has results:
+
+   - we return a [text response](https://docs.moveo.ai/docs/get_started/response_text) informing the user for the number of the results.
+   - then we return a [carousel](https://docs.moveo.ai/docs/get_started/response_carousel)
+
+2. In all subsequent calls for more results:
+   - we return only a carousel
+3. There are no results from the search:
+   - we return a text response to inform the user.
+4. The `page_number` is negative:
+   - we return a text response informing the user that there are no more results
+
+When creating the carousel if there are more than 5 results left to show, the carousel has 5 [event](#event-card) cards and one [view more](#view-more-card) card. Otherwise it contains only `event cards`.
+
+#### Event card
+
+<img src="../../../public/assets/event_card.png"  width=50% height=50%>
+
+#### View more card
+
+<img src="../../../public/assets/view_more_card.png"  width=50% height=50%>
+
+## Route 2: /api/book-tickets/get-event-dates
+
+This is a POST endpoint that you can call like this:
+
+```sh
+curl -X POST -H "Content-Type: application/json" -H "X-Signature: <YOUR_SIGNATURE>" -d '{ "lang": "en", "context": {"event_id": "5878857406"}}' "https://integration-guides.moveo.ai/api/book-tickets/get-event-dates"
+```
+
+It returns a **text response** with **options** consisting of the available dates for a specific event.
+
+<img src="../../../public/assets/event_dates.png"  width=300px height=50%>
+
+### Quick overview of the code:
+
+1. Validate request
+2. Extract context variables from the request body
+3. Check for missing parameters
+4. Get the dates from a dummy endpoint
+5. Create and return a text response using the dates
+
+### Parameters (context variables)
+
+| Name     | Required | Type   | Description                   |
+| -------- | -------- | ------ | ----------------------------- |
+| event_id | required | number | The 10-digit id of the event. |
+
+## Route 3: /api/book-tickets/calculate-total-cost
+
+This is a POST endpoint that you can call like this:
+
+```sh
+curl -X POST -H "Content-Type: application/json" -H "X-Signature: <YOUR_SIGNATURE>" -d '{ "lang": "en", "context": {"event_id": "5878857406"}}' "https://integration-guides.moveo.ai/api/book-tickets/get-event-dates"
+```
+
+It does a simple calculation and adds the `total_cost` variable to the context of the dialog.
+
+### Quick overview of the code:
+
+1. Validate request
+2. Extract context variables from the request body
+3. Check for missing parameters
+4. Return and add `total_cost` variable to context
+
+### Parameters (context variables)
+
+| Name           | Required | Type   | Description                   |
+| -------------- | -------- | ------ | ----------------------------- |
+| tickets_amount | required | number | The amount of tickets to book |
+| price          | required | number | The price of each ticket      |

pages/api/book-tickets/get-events.ts

@@ -24,9 +24,10 @@ const handler = async (
   if (req.method !== 'POST') {
     throw new MethodNotAllowed(req.method);
   }
-
+  // Validate request
   checkHmacSignature(req, GET_EVENTS_TOKEN);
 
+  // Extract context variables from the request body
   const ctx = req?.body?.context as GetEventsContext;
   const {
     event_type_value: event_type,
@@ -38,6 +39,7 @@ const handler = async (
     brain_id,
   } = ctx;
 
+  // Check for missing parameters
   const params: string[] = [];
   if (!event_type) params.push('event_type_value');
   if (!area) params.push('area');
@@ -49,7 +51,7 @@ const handler = async (
 
   const log = req.log.child({ session_id, channel, brain_id, lang });
 
-  // Pages are used for subsequent searches
+  // Extract page. When page_number is negative we return a text response.
   let page = 0;
   if (page_number) {
     if (page_number < 0) {
@@ -59,6 +61,7 @@ const handler = async (
   }
 
   try {
+    // Get the data from dummy endpoint
     const resp = await API.getEvents(
       log,
       event_type,
@@ -68,6 +71,7 @@ const handler = async (
       req.id,
       req.moveo_id
     );
+    // Return a carousel using the data
     res.json(formatEventSearchResponse(resp, event_type, area, page, lang));
   } catch (error) {
     const message = `Error fetching events with type: ${event_type} and area: ${area}`;

pages/api/book-tickets/util/responses.ts

@@ -109,7 +109,6 @@ export const formatEventSearchResponse = (
     },
   };
 };
-
 export const formatNoMoreEventsResponse = (
   eventType: EventType,
   area: string

pages/api/lead-generation/README.md

@@ -0,0 +1,54 @@
+# Webhooks used in **Real estate lead generation** brain template
+
+For general information about using webhooks in Moveo you can check our [documentation](https://docs.moveo.ai/docs/get_started/webhooks)
+
+`find-property` [/api/lead-generation/find-property](#route-1-apilead-generationfind-property)
+
+## Route 1: /api/lead-generation/find-property
+
+This is a POST endpoint that you can call like this:
+
+```sh
+curl -X POST -H "Content-Type: application/json" -H "X-Signature: <YOUR_SIGNATURE>" -d '{ "lang": "en", "context": {"offering_type_value": "buy", "area": "Center", "property_type_value": "apartment", "price": "100000", "size": "30"}}' "https://integration-guides.moveo.ai/api/lead-generation/find-property"
+```
+
+It returns a **carousel** consisting of available properties with filters: _areas_, _property_type_value_, _offering_type_value_, _price_, _size_.
+
+### Quick overview of the code:
+
+1. Validate request
+2. Extract context variables, entities and message from the request body
+3. Check for missing parameters
+4. Extract areas
+5. Create size and price limits
+6. Extract page
+7. Extract offering type
+8. Get the data from dummy endpoint
+9. Create and return a carousel using the data
+
+### Parameters (context variables)
+
+| Name                | Required | Type   | Description                                                                                                                                                                                            |
+| ------------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| property_type_value | required | string | The type of the properties. <br /> <br /> Supported values: `apartment`, `detached`, `floor`, `hotel`, `industrial`, `maisonette`, `offices`, `villa`, `block-of-flats`, `retail-leisure`, `land-plot` |
+| offering_type       | required | string | The offering type to differentiate tenants from buyers <br /> <br /> Supported values: `buy`, `rent`                                                                                                   |
+| price               | required | number | An integer that is used as the upper limit for price of the properties                                                                                                                                 |
+| size                | required | number | An integer that is used as the lower limit for size of the properties                                                                                                                                  |
+| pageNumber          | optional | number | An integer that is used for paginating the results                                                                                                                                                     |
+| areas_msg           | optional | string | The answer message of the user for the question "For which areas are you interested"                                                                                                                   |
+| area                | optional | string | The matched area entity                                                                                                                                                                                |
+| search_areas        | optional | string | The initial areas, used for subsequent searches                                                                                                                                                        |
+
+### Responses
+
+There are 2 possible scenarios of the webhook completing successfully:
+
+1. The `page_number` is missing from the context (should be the first time the webhook is called) and the search has results:
+
+   - we return a [text response](https://docs.moveo.ai/docs/get_started/response_text) informing the user for the number of the results.
+   - then we return a [carousel](https://docs.moveo.ai/docs/get_started/response_carousel)
+
+2. In all subsequent calls for more results:
+   - we return only a carousel
+3. There are no results from the search:
+   - we return a text response to inform the user.

pages/api/lead-generation/find-property.ts

@@ -92,8 +92,11 @@ const handler = async (
     req.log.warn(message);
     return res.json(formatError(5, message));
   }
+
+  // Create the search limits for price and size
   const highPrice = price * 1.15;
   const lowSize = size * 0.85;
+
   // Pages are used for subsequent searches
   let page = 0;
   if (pageNumber) {