ti2 1.0.10 → 1.0.13

package/README.md

@@ -4,6 +4,12 @@ Ti2 (Tourism Information Interchange) is an open source integration framework, b
 
 Core functions of Ti2 are currently focused on content, rates, and bookings.
 
+### Why use it ?
+
+Ti2 gives a free, open source solution to building integrations across our industry. In addition, tools can be built on top of Ti2, that add additional value to these integrations - whether for the good of our industry or for profit.
+
+**Become part of the community, start building on Ti2 today!**
+
 ## About this Project
 
 ### How it Works
@@ -16,84 +22,52 @@ App Plugins are value added tools that only speak to Ti2 and other plugins. For
 
 Ti2 can be deployed on your own servers, or you can connect to a Ti2 instance that another company is hosting.
 
-### Why use Ti2 ?
-
-Ti2 gives a free, open source solution to building integrations across our industry. In addition, tools can be built on top of Ti2, that add additional value to these integrations - whether for the good of our industry or for profit.
-
-**Become part of the community, start building on Ti2 today!**
-
-## Getting Started
+### Security
 
-### Requirements
+An admin api key is set trough an environment variable called adminKey; using this API key is possible to create Users and/or application authentications.
 
-Some environment variables are required for ti2 to start
+A new User / User Authentication can be created using the endpoint [createUserToken](https://ti2.tourconnect.dev/api-docs/#/admin/createUserToken); the return value consists of a JWT token for further user intraction with the App; the admin API key is required; no password is saved on the server side.
 
-- DB_URL (mysql connection in url format)
-- dbCryptoKey (integration details encription key, should be a 32 chars random string base64 encoded)
-- adminKey (a key for admin related requests)
-- jwtKey (a key to encrypt user sessions request)
-- frontendKey (an additional optional key to validate the origin of the requests)
-- PORT (an optional port to run the http server, in case a port is not specified as a parameter)
+Apps / Integrations can be created using the admin API Key; this after the plugin had been added to the codebase; the app can be created using the endpoint [createApp](https://ti2.tourconnect.dev/api-docs/#/admin/createApp); such endpoint returns a key that can be used by the app to interact with user Ids; such interactions allow the app to push for changes related to user integrations, the app can list the users currently configured for it using the endpoint [listAppTokens](https://ti2.tourconnect.dev/api-docs/#/app/listAppTokens); the passwords for Apps are encripted onde the database using aes-256-cbc, more details can be found on the [``models/integrations.js``](https://github.com/ti2travel/ti2/blob/main/models/integration.js) file.
 
-### Starting your server
+User + app integration credentials can be added after the app has been added to the system; these can be added by either the user, admin or the app itself using the endpoint [createAppToken](https://ti2.tourconnect.dev/api-docs/#/app/createAppToken). These keys are saved in JWT format on the database.
 
-You can start your own instance by adding a requirement on your own nodejs project as follows:
+## Getting Started
 
-```bash
-$ npm i ti2
-```
+You can start follow [this guide]{@tutorial setup-your-instance} to create an instance, if you want to add an integration (like for your own backend) or add a new internal funtionality you can [create a plugin]{@tutorial plugin-development} for your system.
 
-To start the server with default values use the following: 
+By default a ti2 instance serves a documentation page on the url (http://[yourinstance]/api-docs/) that serves the available API restfull methods, you can review the [swagger documentation page online](https://ti2-staging.tourconnect.com/api-docs/) .
 
-```javascript
-const ti2 = require('ti2')({
-  plugins: {
-    travelgate: require('ti2-travelgate'),
-    ventrata: require('ti2-ventrata'),
-    tourconnect: require('ti2-tourconnect'),
-  },
-});
-```
 
 ## Plugins
 
 Plugins are the connectores to other systems and/or features you intent to use; by default the server will start an API service on port 10010 and the swagger documentation on the path //api-docs, (you can disable wither by passing the startServer param as False or the apiDocs as False.
 
-Plugin environment keys are passed down to the instance while is being created, this is the preferred way of accesing environmen keys from the plugins, such values are not design to hold client / user's API keys or specific data, they are to be stored on the database itself via the AppKey collection.
-
-Plugin ENV variable name convention: ti2_pluginName_environmenVariableName, for example:
-
-```env
-ti2_tourconnect_apiUrl=http://backend:8080
-```
-
-### Available Plugins
-
-| Repo | Features | Maintainer |
-| ---- | -------- | ---------- |
-| [ti2-ventrata](https://github.com/TourConnect/ti2-ventrata)     | Bookings: Search, Cancellation | TourConnect |
-| [ti2-travelgate](https://github.com/TourConnect/ti2-travelgate) | Bookings: Search, Cancellation | TourConnect |
-
-## API logging
-
-Currently logging is supported via elastic search, an elasticLogClient value can ben passed down, example:
-
-```javascript
-const { Client } = require('@elastic/elasticsearch');
-const elasticLogsClient = (() => {
-  if (!elasticLogs) return null;
-  return new Client({ node: elasticLogs });
-})();
-
-const ti2 = require('ti2')({
-  elasticLogsClient,
-  plugins: {
-    ventrata: require('ti2-ventrata'),
-    travelgate: require('ti2-travelgate'),
-    tourconnect: require('ti2-tourconnect'),
-  },
-});
-```
+### Plugin Library
+
+| Methods | [Ventrata](https://github.com/TourConnect/ti2-ventrata) | [TravelGateX](https://github.com/TourConnect/ti2-travelgate) | [Didgigo](https://github.com/TourConnect/ti2-didgigo) | [TourConnect](https://github.com/TourConnect/ti2-tourconnect)
+| ---- | -------- | ---------- | ---- | ---- |
+|**Base**|
+|validateToken|||✓|✓|
+|copyMedia||||✓|
+|**Content**|
+|getProfile|||✓|✓|
+|updateProfile||||✓|
+|getLocations|||✓|✓|
+|getLocation|||✓|✓|
+|createLocation|||✓|✓|
+|updateLocation|||✓|✓|
+|getProducts|||✓|✓|
+|getProduct|||✓|✓|
+|createProduct|||✓|✓|
+|updateProduct|||✓|✓|
+|**Bookings**|
+|searchProducts|✓|✓|
+|searchBooking|✓|✓|
+|searchAvailability|✓|✓|
+|searchQuote|✓|✓|
+|createBooking|✓|✓|
+|cancelBooking|✓|✓|
 
 ## Contributing
 
@@ -111,7 +85,7 @@ Feel free to check the [Issues Page](https://github.com/TourConnect/ti2/issues).
 
 ## License
 
-Distributed under the GPL-3 License. See LICENSE.txt for more information.
+Distributed under the GPL-3 License. See LICENSE file for more information.
 
 TL;DR Here's what the license entails:
 

package/api.yml

@@ -141,6 +141,7 @@ components:
             type: string
     bookingSearchQuery:
       type: object
+      additionalProperties: true
       properties:
         bookingId:
           type: string
@@ -172,6 +173,7 @@ components:
           default: "DD/MM/YYYY"
     bookingDetail:
       type: object
+      additionalProperties: true
       properties:
         id:
           type: string
@@ -181,7 +183,15 @@ components:
           type: string
           required: true
           description: The booking status
-
+    bookingSearchQueryResults:
+      type: object
+      additionalProperties: true
+      properties:
+        bookings:
+          type: object
+          required: true
+          items:
+            $ref: '#/components/schemas/bookingDetail'
     bookingDetailsForCancel:
       allOf:     # Combines the BasicErrorModel and the inline model
         - $ref: '#/components/schemas/bookingDetail'
@@ -191,6 +201,89 @@ components:
           type: integer
           required: true
           description: The unix time the cancellation was sent
+    cancellationReturn:
+      type: object
+      properties:
+        cancellation:
+          type: object
+          allOf:     # Combines the BasicErrorModel and the inline model
+            - $ref: '#/components/schemas/bookingDetail'
+    bookingsProductQuery:
+      type: object
+      additionalProperties: true
+      description: Additional properties may be included
+      properties:
+        productName:
+          type: string
+          required: false
+          description: Product Name wildcard match
+          example: '*bus*'
+    bookingsProductSearchReturn:
+      type: object
+      additionalProperties: true
+      description: Additional properties may be included
+      properties:
+        products:
+          type: array
+          required: false
+          description: Product Search Results
+          items: 
+            type: object
+        accommodation:
+          type: array
+          required: false,
+          decription: Accommodation search results
+          items:
+            type: object
+    pricingItem:
+      type: object
+      additionalProperties: true
+      properties:
+        original:
+          type: integer
+        retail:
+          type: integer
+        net:
+          type: integer
+        currency:
+          type: string
+          example: "USD"
+        currencyPrecision:
+          type: integer
+        includedTaxes:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+            properties:
+              name:
+                type: string
+              retail:
+                type: integer
+              net:
+                type: integer
+    availabilityItem:
+      type: object
+      additionalProperties: true
+      properties:
+        id:
+          type: string
+          required: true
+          description: An availability Id that can be used for quoting
+        pricing:
+          $ref: '#/components/schemas/pricingItem'
+          required: false
+        cancelPolicy:
+          type: string
+          required: false
+    bookingRequest:
+      type: object
+      additionalProperties: true
+      required: true
+      properties:
+        id:
+          type: string
+          description: a quote Id to make a reservation for
 paths:
   /ping:
     get:
@@ -516,10 +609,12 @@ paths:
             schema:
               $ref: '#/components/schemas/bookingSearchQuery'
       responses:
-        description: search results
-        content:
-          application/json:
-            schema: '#/components/schemas/AnyValue'
+        '200':
+          description: search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bookingSearchQueryResults'
   /bookings/{appKey}/{userId}/{hint}/search:
     post:
       security:
@@ -557,10 +652,12 @@ paths:
             schema:
               $ref: '#/components/schemas/bookingSearchQuery'
       responses:
-        description: search results
-        content:
-          application/json:
-            schema: '#/components/schemas/AnyValue'
+        '200':
+          description: search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bookingSearchQueryResults'
   /bookings/{appKey}/{userId}/cancel:
     post:
       security:
@@ -591,10 +688,12 @@ paths:
             schema:
               $ref: '#/components/schemas/bookingDetailsForCancel'
       responses:
-        description: search results
-        content:
-          application/json:
-            schema: '#/components/schemas/AnyValue'
+        '200':
+          description: Cancellation confirmation details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/cancellationReturn'
   /bookings/{appKey}/{userId}/{hint}/cancel:
     post:
       security:
@@ -632,7 +731,373 @@ paths:
             schema:
               $ref: '#/components/schemas/bookingDetailsForCancel'
       responses:
-        description: search results
+        '200':
+          description: Cancellation confirmation details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/cancellationReturn'
+  /products/{appKey}/{userId}/search:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Product Search
+      operationId: bookingsProductSearch
+      parameters:
+        - name: appKey
+          in: path
+          description: app to search the booking products, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: Search query
+        required:  true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bookingsProductQuery'
+      responses:
+        '200':
+          description: search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bookingsProductSearchReturn'
+  /products/{appKey}/{userId}/{hint}/search:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Product Search using for an specific hint
+      operationId: bookingsProductSearch
+      parameters:
+        - name: appKey
+          in: path
+          description: app to search the booking products, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+        - name: hint
+          in: path
+          description: a specific token hint to be used
+          required: true
+          example: 'travelgate-australia'
+          schema:
+            type: string
+      requestBody:
+        description: Search query
+        required:  true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bookingsProductQuery'
+      responses:
+        '200':
+          description: search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bookingsProductSearchReturn'
+  /bookings/{appKey}/{userId}/availability:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Availability Search
+      operationId: bookingsAvailabilitySearch
+      parameters:
+        - name: appKey
+          in: path
+          description: app to search availability for, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: both app details
+        required:  true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AnyValue'
+      responses:
+        '200':
+          description: search results
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  availability:
+                    type: array
+                    required: true
+                    items:
+                      $ref: '#/components/schemas/availabilityItem'
+  /bookings/{appKey}/{userId}/{hint}/availability:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Availability Search for an specific hint
+      operationId: bookingsAvailabilitySearch
+      parameters:
+        - name: appKey
+          in: path
+          description: app to search availability for, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+        - name: hint
+          in: path
+          description: a specific token hint to be used
+          required: true
+          example: 'travelgate-australia'
+          schema:
+            type: string
+      requestBody:
+        description: both app details
+        required:  true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AnyValue'
+      responses:
+        '200':
+          description: search results
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  availability:
+                    type: array
+                    required: true
+                    items:
+                      $ref: '#/components/schemas/availabilityItem'
+  /bookings/{appKey}/{userId}/quote:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Quote an Availability
+      operationId: searchQuote
+      parameters:
+        - name: appKey
+          in: path
+          description: app to quote availability for, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: Availability spec to be quoted
+        required:  true
         content:
           application/json:
-            schema: '#/components/schemas/AnyValue'
+            schema:
+              type: object
+              additionalProperties: true
+              properties:
+                id:
+                  type: string
+                  required: true
+                  description: An availability Id to quote
+      responses:
+        '200':
+          description: Quote Details
+          content:
+            application/json:
+              schema:
+                type: object
+                required: true
+                properties:
+                  quote:
+                    type: array
+                    required: true
+                    items:
+                      type: object
+                      additionalProperties: true
+                      properties:
+                        id:
+                          type: string
+                          description: a quote Id that can be use to book
+  /bookings/{appKey}/{userId}/{hint}/quote:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Quote an Availability for an specific hint
+      operationId: searchQuote
+      parameters:
+        - name: appKey
+          in: path
+          description: app to quote the availability for, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+        - name: hint
+          in: path
+          description: a specific token hint to be used
+          required: true
+          example: 'travelgate-australia'
+          schema:
+            type: string
+      requestBody:
+        description: Availability spec to be quoted
+        required:  true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+              properties:
+                id:
+                  type: string
+                  required: true
+                  description: An availability Id to quote
+      responses:
+        '200':
+          description: Quote Details
+          content:
+            application/json:
+              schema:
+                type: object
+                required: true
+                properties:
+                  quote:
+                    type: array
+                    required: true
+                    items:
+                      type: object
+                      additionalProperties: true
+                      properties:
+                        id:
+                          type: string
+                          description: a quote Id that can be use to book
+  /bookings/{appKey}/{userId}/booking:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Create a Booking
+      operationId: createBooking
+      parameters:
+        - name: appKey
+          in: path
+          description: app to create the booking for, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: Booking creation payload
+        required:  true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bookingRequest'
+      responses:
+        '200':
+          description: Booking Details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AnyValue'
+  /bookings/{appKey}/{userId}/{hint}/booking:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Create a Booking for an specific hint
+      operationId: createBooking
+      parameters:
+        - name: appKey
+          in: path
+          description: app to create the booking for, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+        - name: hint
+          in: path
+          description: a specific token hint to be used
+          required: true
+          example: 'travelgate-australia'
+          schema:
+            type: string
+      requestBody:
+        description: Booking creation payload
+        required:  true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bookingRequest'
+      responses:
+        '200':
+          description: Booking Details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AnyValue'