Merge branch '574_StartChat' of https://github.com/bertrand-s/FDC3 in…

…to bertrand-s-574_StartChat
finos · May 19, 2022 · fef5c5e · fef5c5e
2 parents 1a0c12a + d4fe059
commit fef5c5e
Show file tree

Hide file tree

Showing 9 changed files with 225 additions and 7 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added details of FDC3's existing versioning and deprecation policies to the FDC3 compliance page ([#539](https://github.com/finos/FDC3/pull/539))
 * Added a new experimental features policy, which exempts features designated as experimental from the versioning and deprecation policies, to the FDC3 compliance page ([#549](https://github.com/finos/FDC3/pull/549))
 * Add `IntentDeliveryFailed` to the `ResolveError` enumeration to be used when delivery of an intent and context to a targetted app or instance fails. ([#601](https://github.com/finos/FDC3/pull/601))
+* Added a new context type `ChatInitSettings` to initialize a chat creation with new optional parameters ([#620](https://github.com/finos/FDC3/pull/620))
 
 ### Changed
 * Consolidated `Listener` documentation with other types ([#404](https://github.com/finos/FDC3/pull/404))

diff --git a/docs/context/ref/ChatInitSettings.md b/docs/context/ref/ChatInitSettings.md
@@ -0,0 +1,86 @@
+---
+id: ChatInitSettings
+sidebar_label: ChatInitSettings
+title: ChatInitSettings
+hide_title: true
+---
+
+# `ChatInitSettings`
+
+A collection of settings to start a new chat conversation
+
+## Type
+
+`fdc3.chat.initSettings`
+
+## Schema
+
+https://fdc3.finos.org/schemas/next/chatInitSettings.schema.json
+
+## Details
+
+| Property                       | Type        | Required | Example Value                                                        |
+| ------------------------------ | ----------- | -------- | -------------------------------------------------------------------- |
+| `type`                         | string      | Yes      | `'fdc3.chat.initSettings'`                                           |
+| `chatName`                     | string      | No       | `'Instrumet XYZ'`                                                    |
+| `members`                      | ContactList | No       | ContactList - cf. below                                              |
+| `initMessage`                  | string      | No       | `'Hello!'`                                                           |
+| `options.groupRecipients`      | boolean     | No       | `true`: if false a separate chat will be created for each member     |
+| `options.public`               | boolean     | No       | `true`: the room will be visible to everyone in the chat application |
+| `options.allowHistoryBrowsing` | boolean     | No       | `true`: members will be allowed to browse past messages             |
+| `options.allowMessageCopy`     | boolean     | No       | `true`: members will be allowed to copy/paste messages               |
+| `options.allowAddUser`         | boolean     | No       | `true`: members will be allowed to add other members to the chat     |
+
+If _members_ or _chatName_ are not provided, the application executing this
+intent is expected to provide a means to enter such information.
+
+## Example
+
+```js
+const initSettings = {
+    type: 'fdc3.chat.initSettings',
+    chatName: 'Chat ABCD',
+    members: {
+        type: 'fdc3.contactList',
+        contacts: [{
+            type: 'fdc3.contact',
+            name: 'Jane Doe',
+            id: {
+                email: 'jane@mail.com'
+            }
+        },{
+            type: 'fdc3.contact',
+            name: 'John Doe',
+            id: {
+                email: 'john@mail.com'
+            },
+        }]
+    },
+    options: {
+        groupRecipients: true, // one chat with both contacts
+        public: false, // private chat room
+        allowHistoryBrowsing: true,
+        allowMessageCopy: true
+    }
+    initMessage: 'Hello both!'
+}
+
+const res = fdc3.raiseIntent('StartChat', initSettings);
+const roomRefs = await res.getResult();
+```
+
+## See Also
+
+Other Types
+
+- [ContactList](ContactList)
+
+Intents
+
+- [StartChat](../../intents/ref/StartChat)
+- [StartCall](../../intents/ref/StartCall)
+- [ViewContact](../../intents/ref/ViewContact)
+
+FINOS Financial Objects
+
+- [Contact](https://fo.finos.org/docs/objects/contact)
diff --git a/docs/context/spec.md b/docs/context/spec.md
@@ -80,6 +80,13 @@ The identifier "foo" is proprietary, an application that can use it is free to d
 The following are standard FDC3 context types.
  __Note:__ The specification for these types are shared with the [FINOS Financial Objects](https://fo.finos.org) definitions, JSON schemas are hosted with FDC3.
 
+- __fdc3.chat.initSettings__
+    - Initialization parameters to start a new chat
+    - [Financial Objects Specification](https://fo.finos.org/docs/objects/chatInitSettings)
+    - [schema](/schemas/next/chatInitSettings.schema.json)
+- __fdc3.chat.roomRef__
+    - Room reference object to specify a specific chat room
+    - [schema](/schemas/next/chatRoomRef.schema.json)
 - __fdc3.contact__
     - A person contact that can be engaged with through email, calling, messaging, CMS, etc.
     - [Financial Objects Specification](https://fo.finos.org/docs/objects/contact)
@@ -120,6 +127,34 @@ __Note:__ The below examples show how the base context data interface can be use
 
 ### Examples
 
+#### ChatInitSettings
+```json
+{
+    "type": "fdc3.chat.initSettings",
+    "chatName": "Issue #123",
+    "members": [{
+        "type": "fdc3.contact",
+        "name": "Jane Doe",
+        "id": {
+            "email": "jane@mail.com"
+        }
+    },{
+        "type": "fdc3.contact",
+        "name": "John Doe",
+        "id": {
+            "email": "john@mail.com"
+        },
+    }],
+    "options": {
+        "groupRecipients": true, 
+        "public": false, 
+        "allowHistoryBrowsing": true,
+        "allowMessageCopy": true,
+        "allowAddUser": false, 
+    }
+    "initMessage": "Hello both!"
+}
+```
 #### Contact
 ```json
 {

diff --git a/docs/intents/ref/StartChat.md b/docs/intents/ref/StartChat.md
@@ -6,7 +6,7 @@ hide_title: true
 ---
 # `StartChat`
 
-Initiate a chat with a contact or list of contacts.
+Initiate a chat with a contact, a list of contacts or detailed initialization settings.
 
 ## Intent Name
 
@@ -20,6 +20,7 @@ Initiate a chat with a contact or list of contacts.
 
 * [Contact](../../context/ref/Contact)
 * [ContactList](../../context/ref/ContactList)
+* [ChatInitSettings](../../context/ref/ChatInitSettings)
 
 ## Example
 
@@ -33,13 +34,41 @@ const contact = {
 }
 
 fdc3.raiseIntent('StartChat', contact)
+
+// chat with initialization settings
+const initSettings = {
+    type: 'fdc3.chat.initSettings',
+    chatName: 'Issue #123',
+    members: {
+        type: 'fdc3.contactList',
+        contacts: [{
+            type: 'fdc3.contact',
+            name: 'John Doe',
+            id: {
+                email: 'john@mail.com'
+            },
+        }]
+    },
+    options: {
+        groupRecipients: true, // one chat with both contacts
+        public: false, // private chat room
+        allowHistoryBrowsing: true,
+        allowMessageCopy: true,
+        allowAddUser: false, // John won't be auhtorized to add other users to the chat
+    }
+    initMessage: 'Hello John!'
+}
+
+const resolution = fdc3.raiseIntent('StartChat', initSettings);
+const chatRoomRefs = await resolution.getResult();
 ```
 
 ## See Also
 
 Context
 - [Contact](../../context/ref/Contact)
 - [ContactList](../../context/ref/ContactList)
+- [ChatInitSettings](../../context/ref/ChatInitSettings)
 
 Intents
 - [StartCall](StartCall)
diff --git a/src/context/schemas.json b/src/context/schemas.json
@@ -1,4 +1,7 @@
 {
+  "ChatInitSettings": [
+    "https://fdc3.finos.org/schemas/next/chatInitSettings.schema.json"
+  ],
   "Context": ["https://fdc3.finos.org/schemas/next/context.schema.json"],
   "Contact": ["https://fdc3.finos.org/schemas/next/contact.schema.json"],
   "ContactList": ["https://fdc3.finos.org/schemas/next/contactList.schema.json"],

diff --git a/src/context/schemas/chatInitSettings.schema.json b/src/context/schemas/chatInitSettings.schema.json
@@ -0,0 +1,30 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://fdc3.finos.org/schemas/next/chatInitSettings.schema.json",
+    "type": "object",
+    "title": "ChatInitSettings",
+    "properties": {
+        "type": {
+            "const": "fdc3.chat.initSettings"
+        },
+        "chatName": {
+            "type": "string"
+        },
+        "members": {
+            "$ref": "contactList.schema.json#"
+        },
+        "initMessage": {
+            "type": "string"
+        },
+        "options": {
+            "groupRecipients": "boolean",
+            "public": "boolean",
+            "allowHistoryBrowsing": "boolean",
+            "allowMessageCopy": "boolean",
+            "allowAddUser": "boolean"
+        }
+    },
+    "required": [
+        "type"
+    ]
+}
diff --git a/website/sidebars.json b/website/sidebars.json
@@ -61,15 +61,16 @@
         "label": "Reference",
         "ids": [
           "context/ref/Context",
+          "context/ref/ChatInitSettings",
           "context/ref/Contact",
           "context/ref/ContactList",
+          "context/ref/Country",
           "context/ref/Instrument",
           "context/ref/InstrumentList",
+          "context/ref/Nothing",
           "context/ref/Organization",
-          "context/ref/Country",
-          "context/ref/Position",
           "context/ref/Portfolio",
-          "context/ref/Nothing"
+          "context/ref/Position"
         ]
       }
     ],

diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml
@@ -377,12 +377,15 @@ components:
           items:
             type: string
           description: >-
-            A comma separated list of the types of contexts the intent offered by the application can process, 
+            A comma separated list of the types of contexts the intent offered by the application can process,  
             where the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact"
-        resultContext:
+        resultType:
           type: string
           description: >-
-            The type of context return by the application when resolving this intent. E.g. "fdc3.instrument"
+            An optional type for output returned by the application, if any, when resolving this intent. 
+            May indicate a context type by type name (e.g. "fdc3.instrument"), a channel (e.g. "channel") 
+            or a combination that indicates a channel that returns a particular context type 
+            (e.g. "channel<fdc3.instrument>").
         customConfig:
           type: object
           description: >-

diff --git a/website/static/schemas/next/chatInitSettings.schema.json b/website/static/schemas/next/chatInitSettings.schema.json
@@ -0,0 +1,30 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://fdc3.finos.org/schemas/next/chatInitSettings.schema.json",
+    "type": "object",
+    "title": "ChatInitSettings",
+    "properties": {
+        "type": {
+            "const": "fdc3.chat.initSettings"
+        },
+        "chatName": {
+            "type": "string"
+        },
+        "members": {
+            "$ref": "contactList.schema.json#"
+        },
+        "initMessage": {
+            "type": "string"
+        },
+        "options": {
+            "groupRecipients": "boolean",
+            "public": "boolean",
+            "allowHistoryBrowsing": "boolean",
+            "allowMessageCopy": "boolean",
+            "allowAddUser": "boolean"
+        }
+    },
+    "required": [
+        "type"
+    ]
+}