@deeptrekker/api-domain 0.37.0 → 0.38.0

package/readme.md

@@ -1,61 +1,27 @@
-# DeepTrekker API
+# DeepTrekker BRIDGE Web API
 
 > 💡 Read the [service disclaimer](#⚖%EF%B8%8F-service-disclaimer) before using
 > the API.
 
 ## Intro
 
-This documentation defines the core types, schemas, enumerations, and constructs
-used by client-side applications and server side devices to communicate with
-each other. Together, this forms the entirety of the DeepTrekker API. This API
-is powered by TypeScript and the documentation and samples are generated
-directly from these types.
+The BRIDGE web API is a programming interface we've developed that can be
+utilized by applications, either internal or external to Deep Trekker, for
+standardized communication with across devices within the Deep Trekker
+ecosystem. It is essentially a common language that our devices can understand
+and interpret, enabling them to carry out precise instructions, or send commands
+over to other connected devices for execution.
 
-## Getting Started
+This documentation describes the core types, schemas, enumerations, and
+construct definitions used by client-side applications and server side devices
+to communicate with one another. Furthermore, it also describes the various
+supported connection methods and means of communicating data. Altogether, this
+forms the entirety of the DeepTrekker API.
 
-Refer to the documentation on how to integrate the DeepTrekker API within a
-client-side solution for communicating with DeepTrekker related hardware.
-
-## NPM Packages
-
--   [@deeptrekker/api-domain](https://www.npmjs.com/package/@deeptrekker/api-domain)
-
-    To conform with our api standard, developers should incorporate this package
-    in their client-side JavaScript/Typescript applications. This package
-    contains a schema that defines the precise structure that payloads should be
-    created in that will be understood when parsed by vehicle servers. It also
-    contains well-defined types and constructs that can be directly imported
-    when developing using the same language to streamline the development
-    process.
-
-    > 💡 Since the documentation, and its associated samples, stem from this
-    > package, it should be referred to as the single source of truth for all
-    > clients that implement our API.
-
-    ### Contents
-
-    -   [Version](dist/versions)
-    -   [API Schema](dist/schemas/schema.json)
-    -   [Samples](dist/samples)
-    -   [Generated Samples](dist/samples/generated/)
-        -   [Requests](dist/samples/generated/requests/)
-        -   [States](dist/samples/generated/state/)
-
-    ### Set up
-
-    This package can be installed using the following methods
-
-    1. Install [NPM package manager](https://www.npmjs.com/).
-    1. Navigate to the root of your client application directory.
-    1. In the terminal, run `npm init` to initialize.
-    1. Run `npm install @deeptrekker/api-domain`.
-    1. If you're developing a JS/TS application, you can import the necessary
-       types into your project. Otherwise, you can reference the json schema
-       also provided for validating payloads and conforming to our API.
-
--   [@deeptrekker/sdk](https://google.ca)
-
-    > 👷‍♂️ Under construction
+> 💡 The API documentation and samples found here are generated directly from
+> types and interface definitions from the actual domain code that some of our
+> newer client-side applications make use of. This ensures that both the code
+> and documentation remain up-to-date and stem from a single source of truth.
 
 ## Communication
 
@@ -64,297 +30,390 @@ clients for relaying vehicle data. Under the hood, we are using the most
 versatile technologies and standards available in order to accommodate
 communication across a variety of different technological stacks.
 
-### WebRTC
+### Architecture
+
+The following diagram illustrates a comprehensive view of various devices that
+exist and communicate with one another within the BRIDGE web system. Arrows are
+drawn in to show the flow of data while connection methods are differentiated by
+color.
+
+![postman-wss-1](assets/bridge-api-system-architecture.png)
+
+## Connection Methods
+
+The JSON-based API data that flows through channels is inherently agnostic, so
+any communication protocol could be used to convey Deep Trekker API data.
+However, we have implemented two specific methods of connectivity that are
+officially supported and compatible with our vehicles, controllers and other
+peripheral devices.
+
+### WebRTC Connection
+
+The WebRTC (Web Real-Time Communication) Connection API can be used for
+conveying JSON-based payloads in a web browser-based development environment. It
+provides several features that make it suitable for transmitting data over
+networks, with built-in encryption and optimization for variable network
+qualities. This is a modern web technology that powers peer-peer communication
+which can endure varying degrees of latency and interruptions throughout session
+and send data in ne. To start a session, clients initially have to negotiate via
+a https/websocket handshake with the signal server. Afterwards, they are free to
+communicate and exchange data in real time via numerous parallel data channels.
+In the temporary absence of the signalling server, existing client sessions can
+continue to live on.
+
+-   **Web Compatibility:** The WebRTC Connection API is designed to work in web
+    browsers, making it compatible with various platforms and operating systems.
+    This allows developers to leverage its capabilities without worrying about
+    platform-specific implementations.
 
-Realtime communication can be achieved via WebRTC. This is a modern web
-technology that powers peer-peer communication which can endure varying degrees
-of latency and interruptions throughout session. To start a session, clients
-initially have to negotiate via a https/websocket handshake with the signal
-server. Afterwards, they are free to communicate and exchange data in real time
-via numerous parallel data channels. In the temporary absence of the signalling
-server, existing client sessions can continue to live on.
+-   **Realtime communication:** Realtime communication can be achieved via
+    WebRTC. This is a modern web technology that powers peer-peer communication
+    which can endure varying degrees of latency and interruptions throughout
+    session and send data in ne. To start a session, clients initially have to
+    negotiate via a https/websocket handshake with the signal server.
+    Afterwards, they are free to communicate and exchange data in real time via
+    numerous parallel data channels. In the temporary absence of the signalling
+    server, existing client sessions can continue to live on.
 
-#### Expected Architecture
+-   **Optimization for Variable Network Qualities:** WebRTC is designed to adapt
+    to different network conditions, allowing it to optimize data transmission
+    for varying network qualities. It utilizes adaptive congestion control
+    algorithms to adjust the transmission rate dynamically, optimizing the
+    delivery of JSON payloads based on available bandwidth and network
+    conditions.
 
-It is expected that a 1:1 relationship exists between a peer connection and a
-front-end client. Clients with multiple peer connections are not supported. It
-is expected that one or more data and video channels are to be used within a
-single peer connection. A data channel named "DATA_CHANNEL_API" will be opened
-on connection which facilitates api communications. Through the api the client
-may operate vehicle controls, receive live data, and request video streams.
+-   **Built-in Data Encryption:** The WebRTC Connection API incorporates
+    built-in encryption mechanisms to ensure secure transmission of data. It
+    utilizes standardized encryption protocols such as Secure Real-Time
+    Transport Protocol (SRTP) and Datagram Transport Layer Security (DTLS) to
+    protect the confidentiality and integrity of the transmitted JSON payloads.
 
-Upon request of a video stream, the peer connection will be renegotiated to
-support the requested configuration. Depending on the hardware in use this has
-the potential to require too many resources from the backend and cause a crash.
-It is suggested to keep requested video to 2 1080p streams at a maximum (on
-currently released hardware as of Feb 2023). If more streams are required, the
-lower resolution substreams may be used at the cost of visual quality.
-
-### Signal Server
+-   **Support for Over-the-Internet Connections:** The WebRTC Connection API is
+    specifically designed for establishing real-time communication over the
+    internet. It enables peer-to-peer connections between browsers, allowing
+    data transmission directly between clients without the need for intermediate
+    servers. This direct connectivity enables efficient transmission of JSON
+    payloads across the internet, reducing latency and improving the overall
+    user experience.
 
-To initialize a WebRTC communication room, a client would first need to contact
-the signalling server and negotiate a connection. This is done by performing a
-sequence of handshakes between a client and the signalling server. Afterwards,
-both the vehicle client and the controller clients can freely communicate with
-one another and sent/receive data.
+#### WebRTC Connection Architecture
 
-> 💡 In the context of the DeepTrekker (WebRTC) API, we refer to the vehicle
-> client of the Signal Server as the **vehicle server**.
+-   **Signal Server**
 
-#### SignalR
+    To initialize a WebRTC communication room, a client would first need to
+    contact the signalling server and negotiate a connection. This is done by
+    performing a sequence of handshakes between a client and the signalling
+    server. Afterwards, both the vehicle client and the controller clients can
+    freely communicate with one another and sent/receive data.
 
-Clients can optionally integrate SignalR in client-side code to handle
-signalling negotiation and subsequent receive/send messages with a **vehicle
-server**. We use SignalR to encapsulate some of the complexity of WebRTC
-connections and use its protocols where applicable.
+    > 💡 In the context of the DeepTrekker (WebRTC) API, we refer to the vehicle
+    > client of the Signal Server as the **vehicle server**.
 
-Documentation on how to integrate client-side SignalR code can be found here:
-https://docs.microsoft.com/en-us/aspnet/core/signalr/client-features?view=aspnetcore-3.1
+-   ** SignalR**
 
-> 💡 SignalR has "hubs" instead of "rooms" as a space for client communication.
-> We will use the terms **room** and **hub** interchangeably throughout the
-> documentation.
+    Clients can optionally integrate SignalR in client-side code to handle
+    signalling negotiation and subsequent receive/send messages with a **vehicle
+    server**. We use SignalR to encapsulate some of the complexity of WebRTC
+    connections and use its protocols where applicable.
 
-#### Manual Negotiation (No library)
+    Documentation on how to integrate client-side SignalR code can be found
+    here:
+    https://docs.microsoft.com/en-us/aspnet/core/signalr/client-features?view=aspnetcore-3.1
 
-For client side implementations that do not have access to a SignalR library,
-the following language agnostic handshake steps can be performed to establish a
-wss connection for communication with SignalR endpoints.
+    > 💡 SignalR has "hubs" instead of "rooms" as a space for client
+    > communication. We will use the terms **room** and **hub** interchangeably
+    > throughout the documentation.
 
-Please note that when populating the `arguments` field within websocket messages
-the value is a stringified json field matching the indicated object definitions
-(ie [session_check](interfaces/ISessionCheck.html),
-[join_session](interfaces/IJoinSession.html), etc).
+-   **Manual Negotiation (No library)**
 
-> 💡
-> [Here is some documentation on websockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications)
+    For client side implementations that do not have access to a SignalR
+    library, the following language agnostic handshake steps can be performed to
+    establish a wss connection for communication with SignalR endpoints.
 
-Refer to the following steps that also include pictures illustrating how to
-perform the ceremony using [Postman](https://www.postman.com/downloads/).
+    Please note that when populating the `arguments` field within websocket
+    messages the value is a stringified json field matching the indicated object
+    definitions (ie [session_check](interfaces/ISessionCheck.html),
+    [join_session](interfaces/IJoinSession.html), etc).
 
-1.  Send an http post request to signalling server (replace 'localhost' with the
-    IP address of the BridgeBox)
+    > 💡
+    > [Here is some documentation on websockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications)
 
-    -   URL: `https://localhost:5001/sessionHub/negotiate?negotiateVersion=1`
-        -   Query item: `negotiateVersion=1` (included in URL above)
+    Refer to the following steps that also include pictures illustrating how to
+    perform the ceremony using [Postman](https://www.postman.com/downloads/).
 
-    ![postman-wss-1](assets/postman-wss-1.png)
+    1.  Send an http post request to signalling server (replace 'localhost' with
+        the IP address of the BridgeBox)
 
-1.  Get the "connectionToken" from the reply of the post request and use it to
-    open a web socket to connect to signalling server (replace 'localhost' with
-    the IP address of the BridgeBox)
+        -   URL:
+            `https://localhost:5001/sessionHub/negotiate?negotiateVersion=1`
+            -   Query item: `negotiateVersion=1` (included in URL above)
 
-    -   URL: `wss://localhost:5001/sessionHub?id=` + `connectionToken`
-    -   Open web socket with the above URL (click "New" button beside "My
-        workspace" bar in top left corner)
+        ![postman-wss-1](assets/postman-wss-1.png)
 
-    ![postman-wss-2](assets/postman-wss-2.png)
+    1.  Get the "connectionToken" from the reply of the post request and use it
+        to open a web socket to connect to signalling server (replace
+        'localhost' with the IP address of the BridgeBox)
 
-1.  Send either of the following json objects as an initial payload via WSS
-    protocol to connect to the HUB.
+        -   URL: `wss://localhost:5001/sessionHub?id=` + `connectionToken`
+        -   Open web socket with the above URL (click "New" button beside "My
+            workspace" bar in top left corner)
 
-    -   payload (in plain text)
+        ![postman-wss-2](assets/postman-wss-2.png)
 
-        **⚠️ Ensure you copy this entire line including the invisible Record
-        Separator "RS" ASCII character (`\x1E`) immediately following the "}"
-        bracket:**
+    1.  Send either of the following json objects as an initial payload via WSS
+        protocol to connect to the HUB.
 
-            {"protocol":"json", "version":1}
+        -   payload (in plain text)
 
-    -   base64 encoded payload (includes the "RS" character)
+            **⚠️ Ensure you copy this entire line including the invisible Record
+            Separator "RS" ASCII character (`\x1E`) immediately following the
+            "}" bracket:**
 
-            eyJwcm90b2NvbCI6Impzb24iLCAidmVyc2lvbiI6MX0e
+                {"protocol":"json", "version":1}
 
-    > 💡 No other wss payloads will work until this one is sent first as the
-    > initial payload. You must include the invisible "RS" ascii character at
-    > the end of every payload thereafter as well. This is used to determine the
-    > end and start of different payloads.
-    > [Read more about SignalR's use of the Record Separator.](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md#overview)
+        -   base64 encoded payload (includes the "RS" character)
 
-    ![postman-wss-3](assets/postman-wss-3.png)
+                eyJwcm90b2NvbCI6Impzb24iLCAidmVyc2lvbiI6MX0e
 
-1.  After sending the initial json protocol payload, a payload response with an
-    empty JSON object will be returned by the WSS endpoint.
+        > 💡 No other wss payloads will work until this one is sent first as the
+        > initial payload. You must include the invisible "RS" ascii character
+        > at the end of every payload thereafter as well. This is used to
+        > determine the end and start of different payloads.
+        > [Read more about SignalR's use of the Record Separator.](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/HubProtocol.md#overview)
 
-    -   The empty JSON message from server through web socket signals a
-        successful connection to the signalling server
+        ![postman-wss-3](assets/postman-wss-3.png)
 
-1.  Send a [session_check](interfaces/ISessionCheck.html) message. Be sure to
-    include the "RS" ascii character at the end of any payload sent. After
-    constructing your `arguments` json, stringify it and then construct the rest
-    of the message as shown. This pattern will be followed in the rest of the
-    sent messages.
+    1.  After sending the initial json protocol payload, a payload response with
+        an empty JSON object will be returned by the WSS endpoint.
 
-    -   Client requests list of sessions that are available to join
+        -   The empty JSON message from server through web socket signals a
+            successful connection to the signalling server
 
-        ```json
-        {
-            "arguments": ["{\"client_id\": \"test\"}"],
-            "invocationId": "0",
-            "streamIds": [],
-            "target": "session_check",
-            "type": 1
-         }
-        ```
+    1.  Send a [session_check](interfaces/ISessionCheck.html) message. Be sure
+        to include the "RS" ascii character at the end of any payload sent.
+        After constructing your `arguments` json, stringify it and then
+        construct the rest of the message as shown. This pattern will be
+        followed in the rest of the sent messages.
 
-1.  Await a [session_list](interface/ISessionList.html) message.
+        -   Client requests list of sessions that are available to join
 
-    -   Client receives list of sessions that are available to them
-
-        ```json
-        {
-            "type":1,
-            "target":"session_info",
-            "arguments":[{
-                "session_id":"33555648",
-                "connection_id":"ispG-PRx-G6BiFKrjGMn1A",
-                "clients":[{}]
-            }]
-        }
-        ```
-
-1.  Send a [join_session](interfaces/IJoinSession.html) message.
+            ```json
+            {
+                "arguments": ["{\"client_id\": \"test\"}"],
+                "invocationId": "0",
+                "streamIds": [],
+                "target": "session_check",
+                "type": 1
+            }
+            ```
 
-    -   Client requests to join an available session
+    1.  Await a [session_list](interface/ISessionList.html) message.
 
-        ```json
-        {
-            "arguments": ["{\"client_id\": \"test\", session_id:\"33555648\"}"],
-            "invocationId": "0",
-            "streamIds": [],
-            "target": "join_session",
-            "type": 1
-        }
-        ```
+        -   Client receives list of sessions that are available to them
 
-1.  WebRTC SDP negotiation will be initiated by the backend by sending an offer
-    and ice candidates
+            ```json
+            {
+                "type":1,
+                "target":"session_info",
+                "arguments":[{
+                    "session_id":"33555648",
+                    "connection_id":"ispG-PRx-G6BiFKrjGMn1A",
+                    "clients":[{}]
+                }]
+            }
+            ```
 
-## WebRTC SDP Negotiation
+    1.  Send a [join_session](interfaces/IJoinSession.html) message.
 
-The next part of the negotiation involves negotiating the SDP.
-[A good video example can be found here.](https://research.edm.uhasselt.be/jori/page/Misc/QtWebRTC.html)
+        -   Client requests to join an available session
 
-> 💡 Ensure the JSON payloads are structured with correctly formatted values for
-> their types. Even if it looks like a number but the interface has it as type
-> string, it should still be wrapped in double quotes when sent in a payload to
-> ensure error-free deserialization by strongly-typed languages.
+            ```json
+            {
+                "arguments": ["{\"client_id\": \"test\", session_id:\"33555648\"}"],
+                "invocationId": "0",
+                "streamIds": [],
+                "target": "join_session",
+                "type": 1
+            }
+            ```
 
-1.  Await a [session_info](interfaces/ISessionList.html) message.
+    1.  WebRTC SDP negotiation will be initiated by the backend by sending an
+        offer and ice candidates
 
-    -   Client receives requested session information, should see themselves in
-        the session_info
+-   **WebRTC SDP Negotiation**
 
-        ```json
-        {
-            "type":1,
-            "target":"session_info",
-            "arguments":[{
-                "session_id":"33555648",
-                "connection_id":"ispG-PRx-G6BiFKrjGMn1A",
-                "clients":[{
-                    "client_id":"test",
-                    "connection_id":"odQS6Kiei5y0AaaoZdO5Pw"
-                }]
-            }]
-        }
-        ```
+    The next part of the negotiation involves negotiating the SDP.
+    [A good video example can be found here.](https://research.edm.uhasselt.be/jori/page/Misc/QtWebRTC.html)
 
-1.  Await an [offer](interfaces/IOffer.html) message.
+    > 💡 Ensure the JSON payloads are structured with correctly formatted values
+    > for their types. Even if it looks like a number but the interface has it
+    > as type string, it should still be wrapped in double quotes when sent in a
+    > payload to ensure error-free deserialization by strongly-typed languages.
 
-    -   Client receives the offer from the vehicle
+    1.  Await a [session_info](interfaces/ISessionList.html) message.
 
-        ```json
-        {
-            "type":1,
-            "target":"offer",
-            "arguments":[
-                "{\n  \"target\": \"odQS6Kiei5y0AaaoZdO5Pw\",\n  \"caller\": \"ispG-PRx-G6BiFKrjGMn1A\",\n  \"sessionId\": \"33555648\",\n  \"sdp\": {\n    \"type\": \"offer\",\n    \"sdp\": \"v=0\\r\\no=- 272599448504607653 2 IN IP4 127.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\na=msid-semantic: WMS\\r\\nm=application 9 UDP/DTLS/SCTP webrtc-datachannel\\r\\nc=IN IP4 0.0.0.0\\r\\na=ice-ufrag:H9aZ\\r\\na=ice-pwd:aGo/p9pm1eUS1Aw2qzbgYuQy\\r\\na=ice-options:trickle\\r\\na=fingerprint:sha-256 2D:85:37:C8:CD:64:56:11:7E:A3:65:0D:E4:76:DB:70:AA:05:5B:D9:63:4C:04:24:F2:31:83:DB:BD:C6:6D:EF\\r\\na=setup:actpass\\r\\na=mid:0\\r\\na=sctp-port:5000\\r\\na=max-message-size:262144\\r\\n\"\n  }\n}"
-            ]
-        }
-        ```
+        -   Client receives requested session information, should see themselves
+            in the session_info
 
-1.  Send an [answer](interfaces/IAnswer.html) message.
+            ```json
+            {
+                "type":1,
+                "target":"session_info",
+                "arguments":[{
+                    "session_id":"33555648",
+                    "connection_id":"ispG-PRx-G6BiFKrjGMn1A",
+                    "clients":[{
+                        "client_id":"test",
+                        "connection_id":"odQS6Kiei5y0AaaoZdO5Pw"
+                    }]
+                }]
+            }
+            ```
 
-    -   Client sends their answer to the signaling server
+    1.  Await an [offer](interfaces/IOffer.html) message.
 
-        ```json
-        {
-            "type":1,
-            "target":"answer",
-            "invocationId":"3",
-            "arguments":[
-                "{\"caller\":\"odQS6Kiei5y0AaaoZdO5Pw\",\"sdp\":{\"sdp\":\"v=0\\r\\no=- 6398202607803557374 2 IN IP4 127.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\na=msid-semantic: WMS\\r\\nm=application 9 UDP/DTLS/SCTP webrtc-datachannel\\r\\nc=IN IP4 0.0.0.0\\r\\na=ice-ufrag:heL6\\r\\na=ice-pwd:VasvuVpgy6Alpi9q4np1OGWX\\r\\na=ice-options:trickle\\r\\na=fingerprint:sha-256 66:D8:E7:9F:35:2C:68:4E:D8:01:30:F2:49:A4:D4:81:55:AB:55:8E:15:69:C2:4D:71:48:78:52:22:57:12:98\\r\\na=setup:active\\r\\na=mid:0\\r\\na=sctp-port:5000\\r\\na=max-message-size:262144\\r\\n\",\"type\":\"answer\"},\"sessionId\":\"33555648\",\"target\":\"ispG-PRx-G6BiFKrjGMn1A\"}\n"
-            ]
-        }
-        ```
+        -   Client receives the offer from the vehicle
 
-1.  Send and Receive a [ice_candidate](interfaces/IIceCandidate.html) messages.
+            ```json
+            {
+                "type":1,
+                "target":"offer",
+                "arguments":[
+                    "{\n  \"target\": \"odQS6Kiei5y0AaaoZdO5Pw\",\n  \"caller\": \"ispG-PRx-G6BiFKrjGMn1A\",\n  \"sessionId\": \"33555648\",\n  \"sdp\": {\n    \"type\": \"offer\",\n    \"sdp\": \"v=0\\r\\no=- 272599448504607653 2 IN IP4 127.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\na=msid-semantic: WMS\\r\\nm=application 9 UDP/DTLS/SCTP webrtc-datachannel\\r\\nc=IN IP4 0.0.0.0\\r\\na=ice-ufrag:H9aZ\\r\\na=ice-pwd:aGo/p9pm1eUS1Aw2qzbgYuQy\\r\\na=ice-options:trickle\\r\\na=fingerprint:sha-256 2D:85:37:C8:CD:64:56:11:7E:A3:65:0D:E4:76:DB:70:AA:05:5B:D9:63:4C:04:24:F2:31:83:DB:BD:C6:6D:EF\\r\\na=setup:actpass\\r\\na=mid:0\\r\\na=sctp-port:5000\\r\\na=max-message-size:262144\\r\\n\"\n  }\n}"
+                ]
+            }
+            ```
 
-    -   Client and Vehicle sends their ice candidates to each other and responds
-        with their ice-candidates
+    1.  Send an [answer](interfaces/IAnswer.html) message.
 
-        -   Receiving
+        -   Client sends their answer to the signaling server
 
             ```json
             {
                 "type":1,
-                "target":"ice_candidate",
+                "target":"answer",
+                "invocationId":"3",
                 "arguments":[
-                    "{\n  \"target\": \"odQS6Kiei5y0AaaoZdO5Pw\",\n  \"caller\": \"ispG-PRx-G6BiFKrjGMn1A\",\n  \"sessionId\": \"33555648\",\n  \"candidate\": {\n    \"sdpMid\": \"0\",\n    \"sdpMlineIndex\": \"0\",\n    \"content\": \"candidate:557811690 1 udp 2122260223 10.77.100.1 34423 typ host generation 0 ufrag H9aZ network-id 1 network-cost 50\"\n  }\n}"
+                    "{\"caller\":\"odQS6Kiei5y0AaaoZdO5Pw\",\"sdp\":{\"sdp\":\"v=0\\r\\no=- 6398202607803557374 2 IN IP4 127.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\na=msid-semantic: WMS\\r\\nm=application 9 UDP/DTLS/SCTP webrtc-datachannel\\r\\nc=IN IP4 0.0.0.0\\r\\na=ice-ufrag:heL6\\r\\na=ice-pwd:VasvuVpgy6Alpi9q4np1OGWX\\r\\na=ice-options:trickle\\r\\na=fingerprint:sha-256 66:D8:E7:9F:35:2C:68:4E:D8:01:30:F2:49:A4:D4:81:55:AB:55:8E:15:69:C2:4D:71:48:78:52:22:57:12:98\\r\\na=setup:active\\r\\na=mid:0\\r\\na=sctp-port:5000\\r\\na=max-message-size:262144\\r\\n\",\"type\":\"answer\"},\"sessionId\":\"33555648\",\"target\":\"ispG-PRx-G6BiFKrjGMn1A\"}\n"
                 ]
             }
             ```
 
-        -   Sending
+    1.  Send and Receive a [ice_candidate](interfaces/IIceCandidate.html)
+        messages.
+
+        -   Client and Vehicle sends their ice candidates to each other and
+            responds with their ice-candidates
+
+            -   Receiving
+
+                ```json
+                {
+                    "type":1,
+                    "target":"ice_candidate",
+                    "arguments":[
+                        "{\n  \"target\": \"odQS6Kiei5y0AaaoZdO5Pw\",\n  \"caller\": \"ispG-PRx-G6BiFKrjGMn1A\",\n  \"sessionId\": \"33555648\",\n  \"candidate\": {\n    \"sdpMid\": \"0\",\n    \"sdpMlineIndex\": \"0\",\n    \"content\": \"candidate:557811690 1 udp 2122260223 10.77.100.1 34423 typ host generation 0 ufrag H9aZ network-id 1 network-cost 50\"\n  }\n}"
+                    ]
+                }
+                ```
+
+            -   Sending
+
+                ```json
+                {
+                    "type":1,
+                    "target":"ice_candidate",
+                    "invocationId":"4",
+                    "arguments":[
+                        "{\"caller\":\"odQS6Kiei5y0AaaoZdO5Pw\",\"candidate\":{\"content\":\"candidate:1 1 UDP 2122317823 192.168.88.254 56130 typ host\",\"sdpMid\":\"0\",\"sdpMlineIndex\":\"0\"},\"sessionId\":\"33555648\",\"target\":\"ispG-PRx-G6BiFKrjGMn1A\"}\n"
+                    ]
+                }
+                ```
+
+    1.  Run application logic and utilize established Webrtc peer connection to
+        communicate through the API (data channel DATA_CHANNEL_API).
+
+    1.  Send a [leave_session](interfaces/ILeaveSession.html) message when
+        application wants to disconnect.
+
+        -   Client requests to leave the session, other clients in the session
+            and vehicle will receive updated session info
 
             ```json
             {
                 "type":1,
-                "target":"ice_candidate",
-                "invocationId":"4",
-                "arguments":[
-                    "{\"caller\":\"odQS6Kiei5y0AaaoZdO5Pw\",\"candidate\":{\"content\":\"candidate:1 1 UDP 2122317823 192.168.88.254 56130 typ host\",\"sdpMid\":\"0\",\"sdpMlineIndex\":\"0\"},\"sessionId\":\"33555648\",\"target\":\"ispG-PRx-G6BiFKrjGMn1A\"}\n"
+                "target":"leave_session",
+                "invocationId":"0",
+                "arguments":["{\"client_id\":\"test\",    \"session_id\":\"33555648\"}\n"
                 ]
             }
             ```
 
-1.  Run application logic and utilize established Webrtc peer connection to
-    communicate through the API (data channel DATA_CHANNEL_API).
+    1.  A [session_closed](interfaces/IOnDisconnectAsync.html) message will be
+        broadcast to all clients if the vehicle server disconnects.
+
+-   **Video Channel**
+
+    Video streams are transmitted via a dedicated WebRTC data channel between
+    the vehicle server and client.
+
+    > 💡 We refer to this channel as the **video channel**.
 
-1.  Send a [leave_session](interfaces/ILeaveSession.html) message when
-    application wants to disconnect.
+-   **Data Channel**
 
-    -   Client requests to leave the session, other clients in the session and
-        vehicle will receive updated session info
+    Another data channel exists which conveys our API messages between the
+    vehicle server and client bidirectionally via a WebRTC connection. The
+    payloads transmitted on this channel are structured based on the Deep
+    Trekker API constructs shown in this document. The following sections
+    describe these schemas and payloads in detail.
 
-        ```json
-        {
-            "type":1,
-            "target":"leave_session",
-            "invocationId":"0",
-            "arguments":["{\"client_id\":\"test\",    \"session_id\":\"33555648\"}\n"
-            ]
-        }
-        ```
+### Direct Sockets Connection
 
-1.  A [session_closed](interfaces/IOnDisconnectAsync.html) message will be
-    broadcast to all clients if the vehicle server disconnects.
+The Direct Socket Connection API is a simpler method for conveying JSON-based
+payloads which is attractive in the sense that it does not require a handshake
+process to establish a connection. It provides a straightforward approach for
+transmitting data over a socket.
 
-#### Video Channel
+-   **Socket Connection:** The Direct Socket Connection API relies on socket
+    connections, which are low-level communication channels between two
+    endpoints. It allows direct and uninterrupted data transfer between the
+    client and server without any intermediate layers or protocols.
 
-Video streams are transmitted via a dedicated WebRTC data channel between the
-vehicle server and client.
+-   **Connection Establishment:** Unlike protocols such as WebSocket, the Direct
+    Socket Connection API does not involve a handshake process. In traditional
+    socket communication, the client directly establishes a connection with the
+    server using the server's IP address and port number. Once the connection is
+    established, data can be sent and received without any additional
+    negotiation steps.
 
-> 💡 We refer to this channel as the **video channel**.
+-   **Data Transmission:** The Direct Socket Connection API provides a means to
+    send and receive JSON payloads over the established socket connection. The
+    data is typically serialized into a string representation, adhering to the
+    JSON format. The sender converts the JSON payload into a string and
+    transmits it through the socket, while the receiver parses the received
+    string back into JSON for further processing.
 
-#### Data Channel
+It's important to note that the simplicity of the Direct Socket Connection API
+means that it lacks some of the higher-level features found in more complex
+protocols. For example, it does not include built-in encryption, reliability
+mechanisms, or support for handling network issues such as congestion or packet
+loss.
 
-Another data channel exists which conveys our API messages between the vehicle
-server and client bidirectionally via a WebRTC connection. The payloads
-transmitted on this channel are structured based on the Deep Trekker API
-constructs shown in this document. The following sections describe these schemas
-and payloads in detail.
+#### Expected Architecture
+
+It is expected that a 1:1 relationship exists between a peer connection and a
+front-end client. Clients with multiple peer connections are not supported. It
+is expected that one or more data and video channels are to be used within a
+single peer connection. A data channel named "DATA_CHANNEL_API" will be opened
+on connection which facilitates api communications. Through the api the client
+may operate vehicle controls, receive live data, and request video streams.
+
+Upon request of a video stream, the peer connection will be renegotiated to
+support the requested configuration. Depending on the hardware in use this has
+the potential to require too many resources from the backend and cause a crash.
+It is suggested to keep requested video to 2 1080p streams at a maximum (on
+currently released hardware as of Feb 2023). If more streams are required, the
+lower resolution substreams may be used at the cost of visual quality.
 
 ### Payload
 
@@ -502,6 +561,52 @@ hypothetically exist in memory at some point during the operation of a vehicle:
 
 {@codeblock ~~/dist/samples/generated/states/pivotRandomState.json}
 
+## Integration
+
+Refer to the documentation on how to integrate the DeepTrekker API within a
+client-side solution for communicating with DeepTrekker related hardware.
+
+### NPM Packages
+
+-   [@deeptrekker/api-domain](https://www.npmjs.com/package/@deeptrekker/api-domain)
+
+    To conform with our api standard, developers should incorporate this package
+    in their client-side JavaScript/Typescript applications. This package
+    contains a schema that defines the precise structure that payloads should be
+    created in that will be understood when parsed by vehicle servers. It also
+    contains well-defined types and constructs that can be directly imported
+    when developing using the same language to streamline the development
+    process.
+
+    > 💡 Since the documentation, and its associated samples, stem from this
+    > package, it should be referred to as the single source of truth for all
+    > clients that implement our API.
+
+    #### Contents
+
+    -   [Version](dist/versions)
+    -   [API Schema](dist/schemas/schema.json)
+    -   [Samples](dist/samples)
+    -   [Generated Samples](dist/samples/generated/)
+        -   [Requests](dist/samples/generated/requests/)
+        -   [States](dist/samples/generated/state/)
+
+    #### Set up
+
+    This package can be installed using the following methods
+
+    1. Install [NPM package manager](https://www.npmjs.com/).
+    1. Navigate to the root of your client application directory.
+    1. In the terminal, run `npm init` to initialize.
+    1. Run `npm install @deeptrekker/api-domain`.
+    1. If you're developing a JS/TS application, you can import the necessary
+       types into your project. Otherwise, you can reference the json schema
+       also provided for validating payloads and conforming to our API.
+
+-   [@deeptrekker/sdk](https://google.ca)
+
+    > 👷‍♂️ Under construction
+
 ---
 
 ## ⚖️ Service Disclaimer