Merge branch 'main' into fix/bind-this-in-api-objects-and-docs-update

Author: kriswest

CHANGELOG.md

@@ -15,6 +15,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added clarification regarding expected behavior upon repeated calls to `addContextListener` on same or overlapping types (allowed) and `addIntentListener` on same intent (rejected; new error type added). ([#1394](https://github.com/finos/FDC3/pull/1394))
 * Ported FDC3 Conformance Project as-is into the FDC3 Monorepo, just including minimal fixes for typescript compilation. ([#1576](https://github.com/finos/FDC3/pull/1576))
 
+* Added `clearContext` function and associated `contextClearedEvent` to the `Channel` API, to be able to clear specific or all context types from the channel. ([#1379](https://github.com/finos/FDC3/pull/1379))
+
 ### Changed
 
 ### Deprecated

package-lock.json

@@ -1,13 +1,17 @@
-import { ContextHandler, DisplayMetadata, Listener, Channel } from '@finos/fdc3-standard';
+import { ContextHandler, DisplayMetadata, Listener, Channel, EventHandler } from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 import { Messaging } from '../Messaging';
 import { DefaultContextListener } from '../listeners/DefaultContextListener';
 import {
   BroadcastRequest,
   BroadcastResponse,
+  ClearContextRequest,
+  ClearContextResponse,
   GetCurrentContextRequest,
   GetCurrentContextResponse,
 } from '@finos/fdc3-schema/generated/api/BrowserTypes';
+import { RegisterableListener } from '../listeners/RegisterableListener';
+import { EventListener } from '../listeners/EventListener';
 
 export class DefaultChannel implements Channel {
   protected readonly messaging: Messaging;
@@ -103,4 +107,30 @@ export class DefaultChannel implements Channel {
     await listener.register();
     return listener;
   }
+
+  async clearContext(contextType?: string): Promise<void> {
+    // first, ensure channel state is up-to-date
+    const request: ClearContextRequest = {
+      meta: this.messaging.createMeta(),
+      payload: {
+        channelId: this.id,
+        contextType: contextType ?? null,
+      },
+      type: 'clearContextRequest',
+    };
+    await this.messaging.exchange<ClearContextResponse>(request, 'clearContextResponse', this.messageExchangeTimeout);
+  }
+
+  async addEventListener(type: string | null, handler: EventHandler): Promise<Listener> {
+    let listener: RegisterableListener;
+    switch (type) {
+      case 'contextCleared':
+        listener = new EventListener(this.messaging, 'contextCleared', handler);
+        break;
+      default:
+        throw new Error('Unsupported event type: ' + type);
+    }
+    await listener.register();
+    return listener;
+  }
 }

packages/fdc3-agent-proxy/src/channels/DefaultChannel.ts

@@ -114,9 +114,9 @@ export interface ErrorResponseMessagePayload {
  * Constants representing the errors that can be encountered when calling the `open` method
  * on the DesktopAgent object (`fdc3`).
  *
- * Constants representing the errors that can be encountered when calling the `findIntent`,
- * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the
- * DesktopAgent (`fdc3`).
+ * Constants representing the errors that can be encountered when calling the
+ * `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or
+ * `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).
  */
 export type ResponseErrorDetail =
   | 'AccessDenied'
@@ -136,6 +136,7 @@ export type ResponseErrorDetail =
   | 'TargetAppUnavailable'
   | 'TargetInstanceUnavailable'
   | 'UserCancelledResolution'
+  | 'IntentListenerConflict'
   | 'IntentHandlerRejected'
   | 'NoResultReturned'
   | 'AgentDisconnected'
@@ -1134,9 +1135,9 @@ export interface PayloadClass {
  *
  * Should be set if the raiseIntent request returned an error.
  *
- * Constants representing the errors that can be encountered when calling the `findIntent`,
- * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the
- * DesktopAgent (`fdc3`).
+ * Constants representing the errors that can be encountered when calling the
+ * `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or
+ * `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).
  *
  * Array of error message strings for responses that were not returned to the bridge before
  * the timeout or because an error occurred. Should be the same length as the `errorSources`
@@ -1157,6 +1158,7 @@ export type FindInstancesErrors =
   | 'UserCancelledResolution'
   | 'ApiTimeout'
   | 'InvalidArguments'
+  | 'IntentListenerConflict'
   | 'AgentDisconnected'
   | 'NotConnectedToBridge'
   | 'ResponseToBridgeTimedOut'
@@ -2572,9 +2574,9 @@ export interface OpenAgentErrorResponsePayload {
  * the timeout or because an error occurred. Should be the same length as the `errorSources`
  * array and ordered the same. May be omitted if all sources responded without errors.
  *
- * Constants representing the errors that can be encountered when calling the `findIntent`,
- * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the
- * DesktopAgent (`fdc3`).
+ * Constants representing the errors that can be encountered when calling the
+ * `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or
+ * `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).
  */
 export type OpenErrorResponsePayload =
   | 'AppNotFound'
@@ -4031,9 +4033,9 @@ export interface RaiseIntentResultAgentErrorResponsePayload {
  * Constants representing the errors that can be encountered when calling the `open` method
  * on the DesktopAgent object (`fdc3`).
  *
- * Constants representing the errors that can be encountered when calling the `findIntent`,
- * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the
- * DesktopAgent (`fdc3`).
+ * Constants representing the errors that can be encountered when calling the
+ * `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or
+ * `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).
  */
 export type RaiseIntentResultErrorMessage =
   | 'IntentHandlerRejected'
@@ -6489,6 +6491,7 @@ const typeMap: any = {
     'ErrorOnLaunch',
     'IntentDeliveryFailed',
     'IntentHandlerRejected',
+    'IntentListenerConflict',
     'InvalidArguments',
     'MalformedContext',
     'MalformedMessage',
@@ -6538,6 +6541,7 @@ const typeMap: any = {
     'AgentDisconnected',
     'DesktopAgentNotFound',
     'IntentDeliveryFailed',
+    'IntentListenerConflict',
     'InvalidArguments',
     'MalformedContext',
     'MalformedMessage',

packages/fdc3-schema/generated/api/BrowserTypes.ts

@@ -16,7 +16,8 @@
         "intentEvent",
         "privateChannelOnAddContextListenerEvent",
         "privateChannelOnDisconnectEvent",
-        "privateChannelOnUnsubscribeEvent"
+        "privateChannelOnUnsubscribeEvent",
+        "contextClearedEvent"
       ],
       "description": "Identifies the type of the message and it is typically set to the FDC3 function name that the message relates to, e.g. 'findIntent', with 'Response' appended."
     },

packages/fdc3-schema/generated/bridging/BridgingTypes.ts

@@ -35,7 +35,8 @@
         "privateChannelUnsubscribeEventListenerResponse",
         "raiseIntentForContextResponse",
         "raiseIntentResponse",
-        "raiseIntentResultResponse"
+        "raiseIntentResultResponse",
+        "clearContextResponse"
       ],
       "description": "Identifies the type of the message and it is typically set to the FDC3 function name that the message relates to, e.g. 'findIntent', with 'Response' appended."
     },

packages/fdc3-schema/schemas/api/agentEvent.schema.json

@@ -35,7 +35,8 @@
         "privateChannelDisconnectRequest",
         "privateChannelUnsubscribeEventListenerRequest",
         "raiseIntentForContextRequest",
-        "raiseIntentRequest"
+        "raiseIntentRequest",
+        "clearContextRequest"
       ],
       "description": "Identifies the type of the message and it is typically set to the FDC3 function name that the message relates to, e.g. 'findIntent', with 'Request' appended."
     },

packages/fdc3-schema/schemas/api/agentResponse.schema.json

@@ -0,0 +1,56 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://fdc3.finos.org/schemas/next/api/clearContextRequest.schema.json",
+	"type": "object",
+	"title": "Clear Context Request",
+	"description": "A request to clear context on a channel.",
+	"allOf": [
+		{
+			"$ref": "appRequest.schema.json"
+		},
+		{
+			"type": "object",
+			"properties": {
+				"type": {
+					"$ref": "#/$defs/ClearContextRequestType"
+				},
+				"payload": {
+					"$ref": "#/$defs/ClearContextRequestPayload"
+				},
+				"meta": true
+			},
+			"additionalProperties": false
+		}
+	],
+	"$defs": {
+		"ClearContextRequestType": {
+			"title": "Clear Context Request Message Type",
+			"const": "clearContextRequest"
+		},
+		"ClearContextRequestPayload": {
+			"title": "Clear Context Request Payload",
+			"type": "object",
+			"properties": {
+				"channelId": {
+					"title": "Channel Id",
+					"description": "The id of the channel to clear the context on.",
+					"type": "string"
+				},
+				"contextType": {
+					"title": "Context type",
+					"description": "The type of context to clear for OR `null` indicating that all context types on the channel should be cleared.",
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "null"
+						}
+					]
+				}
+			},
+			"required": ["channelId", "contextType"],
+			"additionalProperties": false
+		}
+	}
+}

packages/fdc3-schema/schemas/api/appRequest.schema.json

@@ -0,0 +1,29 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://fdc3.finos.org/schemas/next/api/clearContextResponse.schema.json",
+	"type": "object",
+	"title": "Clear Context Response",
+	"description": "A response to a request to clear context on a channel.",
+	"allOf": [
+		{
+			"$ref": "agentResponse.schema.json"
+		},
+		{
+			"type": "object",
+			"properties": {
+				"type": {
+					"$ref": "#/$defs/ClearContextResponseType"
+				},
+				"payload": true,
+				"meta": true
+			},
+			"additionalProperties": false
+		}
+	],
+	"$defs": {
+		"ClearContextResponseType": {
+			"title": "Clear Context Response Message Type",
+			"const": "clearContextResponse"
+		}
+	}
+}