From 1a76a9b3a051b716f7ff72d8c583c1474e4d4409 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 1 Aug 2024 22:41:09 +0100 Subject: [PATCH 01/13] make Listener.unsubscribe() async --- CHANGELOG.md | 2 ++ docs/api/ref/Types.md | 2 +- src/api/Listener.ts | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fec90b1f..5066044c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Changed +* `Listener.unsubscribe()` was made async (the return type was changed from `void` to `Promise`) for consistency with the rest of the API. ([#X](https://github.com/finos/FDC3/pull/X)) + ### Deprecated * Made `IntentMetadata.displayName` optional as it is deprecated. ([#1280](https://github.com/finos/FDC3/pull/1280)) diff --git a/docs/api/ref/Types.md b/docs/api/ref/Types.md index 48af5671f..87d119415 100644 --- a/docs/api/ref/Types.md +++ b/docs/api/ref/Types.md @@ -148,7 +148,7 @@ A Listener object is returned when an application subscribes to intents or conte ```typescript interface Listener { - unsubscribe(): void; + unsubscribe(): Promise; } ``` diff --git a/src/api/Listener.ts b/src/api/Listener.ts index ced9e2e31..267da7e72 100644 --- a/src/api/Listener.ts +++ b/src/api/Listener.ts @@ -7,5 +7,5 @@ export interface Listener { /** * Unsubscribe the listener object. */ - unsubscribe(): void; + unsubscribe(): Promise; } From 439b49d65eebc830ec4717149720d4a01f24bd25 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 1 Aug 2024 23:23:17 +0100 Subject: [PATCH 02/13] Adjust imports to correct conflict with equivalent type export from ContextTypes --- src/index.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/index.ts b/src/index.ts index 3c1665350..3a2d997db 100644 --- a/src/index.ts +++ b/src/index.ts @@ -6,7 +6,9 @@ import { DesktopAgent } from './api/DesktopAgent'; import * as BridgingTypes from './bridging/BridgingTypes'; -export * from './api/AppIdentifier'; +export * from './context/ContextTypes'; +//explicit overwrite of conflicting & equivalent export from ContextTypes +export {AppIdentifier} from './api/AppIdentifier'; export * from './api/AppIntent'; export * from './api/AppMetadata'; export * from './api/Channel'; @@ -25,7 +27,6 @@ export * from './api/PrivateChannel'; export * from './api/RecommendedChannels'; export * from './api/Types'; export * from './context/ContextType'; -export * from './context/ContextTypes'; export * from './intents/Intents'; export * from './api/Events' From 79c503aae8e6962a803603657986de815b90557b Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 2 Aug 2024 00:10:21 +0100 Subject: [PATCH 03/13] Update PrivateChannel to use the addEventListener pattern --- CHANGELOG.md | 3 + docs/api/ref/Events.md | 99 +++++++++++++++++++++-- docs/api/ref/PrivateChannel.md | 138 ++++++++++++++++++++------------- docs/api/ref/Types.md | 4 +- src/api/Events.ts | 82 +++++++++++++++++--- src/api/PrivateChannel.ts | 55 ++++++++++--- 6 files changed, 298 insertions(+), 83 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5066044c9..300247aaa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added clarification that `id` field values SHOULD always be strings to context schema definition (a restriction that can't easily be represented in the generated types). ([#1149](https://github.com/finos/FDC3/pull/1149)) * Added requirement that Standard versions SHOULD avoid the use unions in context and API definitions wherever possible as these can be hard to replicate and MUST avoid unions of primitive types as these can be impossible to replicate in other languages. ([#120](https://github.com/finos/FDC3/pull/1200)) +* Added `addEventListener` to the `DesktopAgent` API to provide support for event listener for non-context and non-intent events, including a USER_CHANNEL_CHANGED event ([#1207](https://github.com/finos/FDC3/pull/1207)) +* Added an `async` `addEventListener` function to the `PrivateChannel` API to replace the deprecated, synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions and to keep consistency with the DesktopAgent API. ([#X](https://github.com/finos/FDC3/pull/X)) ### Changed @@ -18,6 +20,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Deprecated * Made `IntentMetadata.displayName` optional as it is deprecated. ([#1280](https://github.com/finos/FDC3/pull/1280)) +* Deprecated `PrivateChannel`'s synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions in favour of an `async` `addEventListener` function consistent with the one added to `DesktopAgent`. ([#X](https://github.com/finos/FDC3/pull/X)) ### Fixed diff --git a/docs/api/ref/Events.md b/docs/api/ref/Events.md index c8692018b..276c99155 100644 --- a/docs/api/ref/Events.md +++ b/docs/api/ref/Events.md @@ -2,32 +2,35 @@ title: Events --- -In addition to intent and context events, the FDC3 API may be used to listen for other types of events via the `addEventListener()` function. +In addition to intent and context events, the FDC3 API and PrivateChannel API may be used to listen for other types of events via their `addEventListener()` functions. ## `EventHandler` ```ts -type EventHandler = (event: FDC3Event) => void; +type EventHandler = (event: FDC3Event | PrivateChannelEvent) => void; ``` -Describes a callback that handles non-context and non-intent events. Provides the details of the event. +Describes a callback that handles non-context and non-intent events. Provides the details of the event. -Used when attaching listeners to events. +Used when attaching listeners to events. **See also:** + - [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener) - [`FDC3Event`](#fdc3event) ## `FDC3EventType` + ```ts enum FDC3EventType { USER_CHANNEL_CHANGED = "USER_CHANNEL_CHANGED" } ``` -Enumeration defining the types of (non-context and non-intent) events that may be received via the FDC3 API's `addEventListener` function. +Enumeration defining the types of (non-context and non-intent) events that may be received via the FDC3 API's `addEventListener` function. **See also:** + - [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener) ## `FDC3Event` @@ -39,14 +42,17 @@ interface FDC3Event { } ``` -Type representing the format of event objects that may be received via the FDC3 API's `addEventListener` function. Will always include both `type` and `details`, which describe type of the event and any additional details respectively. +Type representing the format of event objects that may be received via the FDC3 API's `addEventListener` function. + +Events will always include both `type` and `details` properties, which describe the type of the event and any additional details respectively. **See also:** + - [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener) - [`FDC3EventType`](#fdc3eventtype) - ### `FDC3ChannelChangedEvent` + ```ts interface FDC3ChannelChangedEvent extends FDC3Event { readonly type: FDC3EventType.USER_CHANNEL_CHANGED; @@ -56,4 +62,81 @@ interface FDC3ChannelChangedEvent extends FDC3Event { } ``` -Type representing the format of USER_CHANNEL_CHANGED events. The identity of the channel joined is provided as `details.currentChannelId`, which will be `null` if the app is no longer joined to any channel. \ No newline at end of file +Type representing the format of USER_CHANNEL_CHANGED events. + +The identity of the channel joined is provided as `details.currentChannelId`, which will be `null` if the app is no longer joined to any channel. + +## `PrivateChannelEventType` + +```ts +enum PrivateChannelEventType { + ADD_CONTEXT_LISTENER = "addContextListener", + UNSUBSCRIBE = "unsubscribe", + DISCONNECT = "disconnect" +} +``` + +Enumeration defining the types of (non-context and non-intent) events that may be received via a PrivateChannel's `addEventListener` function. + +**See also:** + +- [`PrivateChannel.addEventListener`](PrivateChannel#addEventListener) + +## `PrivateChannelEvent` + +```ts +interface PrivateChannelEvent { + readonly type: PrivateChannelEventType; + readonly details: any; +} +``` + +Type defining the format of event objects that may be received via a PrivateChannel's `addEventListener` function. + +**See also:** + +- [`PrivateChannel.addEventListener`](PrivateChannel#addEventListener) +- [`PrivateChannelEventType`](#privatechanneleventtype) + +### `PrivateChannelAddContextListenerEvent` + +```ts +interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent { + readonly type: PrivateChannelEventType.ADD_CONTEXT_LISTENER; + readonly details: { + contextType: string | null + }; +} +``` + +Type defining the format of events representing a context listener being added to the channel (`addContextListener`). Desktop Agents MUST fire this event for each invocation of `addContextListener` on the channel, including those that occurred before this handler was registered (to prevent race conditions). + +The context type of the listener added is provided as `details.contextType`, which will be `null` if all event types are being listened to. + +### `PrivateChannelUnsubscribeEvent` + +```ts +interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent { + readonly type: PrivateChannelEventType.UNSUBSCRIBE; + readonly details: { + contextType: string | null + }; +} +``` + +Type defining the format of events representing a context listener removed from the channel (`Listener.unsubscribe()`). Desktop Agents MUST call this when `disconnect()` is called by the other party, for each listener that they had added. + +The context type of the listener removed is provided as `details.contextType`, which will be `null` if all event types were being listened to. + +### `PrivateChannelDisconnectEvent` + +```ts +export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent { + readonly type: PrivateChannelEventType.DISCONNECT; + readonly details: null | undefined; +} +``` + +Type defining the format of events representing a remote app being terminated or is otherwise disconnecting from the PrivateChannel. This event is fired in addition to unsubscribe events that will also be fired for any context listeners the disconnecting app had added. + +No details are provided. diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index 5fc8e9c55..5c2024665 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -11,16 +11,19 @@ Object representing a private context channel, which is intended to support secu It is intended that Desktop Agent implementations: - SHOULD restrict external apps from listening or publishing on this channel. -- MUST prevent `PrivateChannels` from being retrieved via fdc3.getOrCreateChannel. +- MUST prevent `PrivateChannels` from being retrieved via `fdc3.getOrCreateChannel`. - MUST provide the `id` value for the channel as required by the `Channel` interface. ```ts interface PrivateChannel extends Channel { - // methods + // functions + addEventListener(type: PrivateChannelEventType | null, handler: EventHandler): Promise; + disconnect(): Promise; + + //deprecated functions onAddContextListener(handler: (contextType?: string) => void): Listener; onUnsubscribe(handler: (contextType?: string) => void): Listener; onDisconnect(handler: () => void): Listener; - disconnect(): void; } ``` @@ -36,34 +39,43 @@ interface PrivateChannel extends Channel { ### 'Server-side' example -The intent app establishes and returns a `PrivateChannel` to the client (who is awaiting `getResult()`). When the client calls `addContextlistener()` on that channel, the intent app receives notice via the handler added with `onAddContextListener()` and knows that the client is ready to start receiving quotes. +The intent app establishes and returns a `PrivateChannel` to the client (who is awaiting `getResult()`). When the client calls `addContextlistener()` on that channel, the intent app receives notice via the handler added with `addEventListener()` and knows that the client is ready to start receiving quotes. The Desktop Agent knows that a channel is being returned by inspecting the object returned from the handler (e.g. check constructor or look for private member). Although this interaction occurs entirely in frontend code, we refer to it as the 'server-side' interaction as it receives a request and initiates a stream of responses. -```typescript +```ts fdc3.addIntentListener("QuoteStream", async (context) => { const channel: PrivateChannel = await fdc3.createPrivateChannel(); const symbol = context.id.ticker; // This gets called when the remote side adds a context listener - const addContextListener = channel.onAddContextListener((contextType) => { - // broadcast price quotes as they come in from our quote feed - feed.onQuote(symbol, (price) => { - channel.broadcast({ type: "price", price}); - }); - }); + const addContextListener = channel.addEventListener("addContextListener", + (event: PrivateChannelAddContextListenerEvent) => { + console.log(`remote side added a listener for ${event.contextType}`); + // broadcast price quotes as they come in from our quote feed + feed.onQuote(symbol, (price) => { + channel.broadcast({ type: "price", price}); + }); + } + ); // This gets called when the remote side calls Listener.unsubscribe() - const unsubscribeListener = channel.onUnsubscribe((contextType) => { - feed.stop(symbol); - }); + const unsubscribeListener = channel.addEventListener("unsubscribe", + (event: PrivateChannelUnsubscribeEvent) => { + console.log(`remote side unsubscribed a listener for ${event.contextType}`); + feed.stop(symbol); + } + ); // This gets called if the remote side closes - const disconnectListener = channel.onDisconnect(() => { - feed.stop(symbol); - }); + const disconnectListener = channel.addEventListener("disconnect", + () => { + console.log(`remote side disconnected`); + feed.stop(symbol); + } + ); return channel; }); @@ -75,88 +87,106 @@ The 'client' application retrieves a `Channel` by raising an intent with context Although this interaction occurs entirely in frontend code, we refer to it as the 'client-side' interaction as it requests and receives a stream of responses. -```javascript +```ts try { const resolution3 = await fdc3.raiseIntent("QuoteStream", { type: "fdc3.instrument", id : { symbol: "AAPL" } }); try { - const result = await resolution3.getResult(); - //check that we got a result and that it's a channel - if (result && result.addContextListener) { - const listener = result.addContextListener("price", (quote) => console.log(quote)); - - //if it's a PrivateChannel - if (result.onDisconnect) { - result.onDisconnect(() => { - console.warn("Quote feed went down"); - }); + const result = await resolution3.getResult(); + //check that we got a result and that it's a channel + if (result && result.addContextListener) { + const listener = result.addContextListener("price", (quote) => console.log(quote)); + //if it's a PrivateChannel + if (result.type == "private") { + result.addEventListener("disconnect", () => { + console.warn("Quote feed went down"); + }); // Sometime later... - listener.unsubscribe(); - } + await listener.unsubscribe(); + } } else { console.warn(`${resolution3.source} did not return a channel`); } } catch(channelError) { - console.log(`Error: ${resolution3.source} returned an error: ${channelError}`); + console.log(`Error: ${resolution3.source} returned an error: ${channelError}`); } } catch (resolverError) { console.error(`Error: Intent was not resolved: ${resolverError}`); } ``` -## Methods +## Functions -### `onAddContextListener` +### `addEventListener` ```ts -onAddContextListener(handler: (contextType?: string) => void): Listener; +addEventListener(type: PrivateChannelEventType | null, handler: EventHandler): Promise; ``` -Adds a listener that will be called each time that the remote app invokes addContextListener on this channel. +Register a handler for events from the PrivateChannel. Whenever the handler function is called it will be passed an event object with details related to the event. + +```ts +// any event type +const listener: Listener = await myPrivateChannel.addEventListener(null, + (event: PrivateChannelEvent) => { + console.log(`Received event ${event.type}\n\tDetails: ${event.details}`); + } +); -Desktop Agents MUST call this for each invocation of addContextListener on this channel, including those that occurred before this handler was registered (to prevent race conditions). +// listener for a specific event type +const channelChangedListener: Listener = await myPrivateChannel.addEventListener( + PrivateChannelEventType.ADD_CONTEXT_LISTENER, + (event: PrivateChannelAddContextListenerEvent) => { ... } +); +``` **See also:** -- [`Channel.addContextListener`](Channel#addcontextlistener) +- [`PrivateChannelEventType`](./Events#privatechanneleventtype) +- [`EventHandler`](./Events#eventhandler) -### `onUnsubscribe` +### `disconnect` ```ts -onUnsubscribe(handler: (contextType?: string) => void): Listener; +disconnect(): Promise; ``` -Adds a listener that will be called whenever the remote app invokes `Listener.unsubscribe()` on a context listener that it previously added. +May be called to indicate that a participant will no longer interact with this channel. -Desktop Agents MUST call this when disconnect() is called by the other party, for each listener that they had added. +After this function has been called, Desktop Agents SHOULD prevent apps from broadcasting on this channel and MUST automatically call Listener.unsubscribe() for each listener that they've added (causing any event handler for `unsubscribe` events added by the other party to be called) before triggering any handlers for `disconnect` events added by the other party. **See also:** - [`Listener`](Types#listener) -### `onDisconnect` +## Deprecated Functions + +### `onAddContextListener` ```ts -onDisconnect(handler: () => void): Listener; +onAddContextListener(handler: (contextType?: string) => void): Listener; ``` -Adds a listener that will be called when the remote app terminates, for example when its window is closed or because disconnect was called. This is in addition to calls that will be made to onUnsubscribe listeners. - -**See also:** +Deprecated in favour of the async `addEventListener("addContextListener", handler)` function. -- [`disconnect`](#disconnect) +Adds a listener that will be called each time that the remote app invokes addContextListener on this channel. -### `disconnect` +### `onUnsubscribe` ```ts -disconnect(): void; +onUnsubscribe(handler: (contextType?: string) => void): Listener; ``` -May be called to indicate that a participant will no longer interact with this channel. +Deprecated in favour of the async `addEventListener("unsubscribe", handler)` function. -After this function has been called, Desktop Agents SHOULD prevent apps from broadcasting on this channel and MUST automatically call Listener.unsubscribe() for each listener that they've added (causing any `onUnsubscribe` handler added by the other party to be called) before triggering any onDisconnect handler added by the other party. +Adds a listener that will be called whenever the remote app invokes `Listener.unsubscribe()` on a context listener that it previously added. -**See also:** +### `onDisconnect` -- [`onUnsubscribe`](#onunsubscribe) -- [`Listener`](Types#listener) +```ts +onDisconnect(handler: () => void): Listener; +``` + +Deprecated in favour of the aysnc `addEventListener("disconnect", handler)` function. + +Adds a listener that will be called when the remote app terminates, for example when its window is closed or because disconnect was called. diff --git a/docs/api/ref/Types.md b/docs/api/ref/Types.md index 87d119415..bd4bfb77d 100644 --- a/docs/api/ref/Types.md +++ b/docs/api/ref/Types.md @@ -144,7 +144,7 @@ Represented as a union type in TypeScript, however, this type may be rendered as ## `Listener` -A Listener object is returned when an application subscribes to intents or context broadcasts via the [`addIntentListener`](DesktopAgent#addintentlistener) or [`addContextListener`](DesktopAgent#addcontextlistener) methods on the [DesktopAgent](DesktopAgent) object. +A Listener object is returned when an application subscribes to intents or context broadcasts via the [`addIntentListener`](DesktopAgent#addintentlistener), [`addContextListener`](DesktopAgent#addcontextlistener) or [`addEventListener`](DesktopAgent#addeventlistener) on the [DesktopAgent](DesktopAgent) object or (PrivateChannel#addeventlistener) on the [PrivateChannel](PrivateChannel) object. ```typescript interface Listener { @@ -155,7 +155,7 @@ interface Listener { ### `unsubscribe` ```ts -unsubscribe(): void; +unsubscribe(): Promise; ``` Allows an application to unsubscribe from listening to intents or context broadcasts. diff --git a/src/api/Events.ts b/src/api/Events.ts index e0f003dac..71fef0b37 100644 --- a/src/api/Events.ts +++ b/src/api/Events.ts @@ -3,12 +3,14 @@ * Copyright FINOS FDC3 contributors - see NOTICE file */ -/** Type representing a handler function for events from the Desktop Agent. - * @param {FDC3Event} event The handler function will be passed an `FDC3Event` Object - * providing details of the event (such as a change of channel membership for the app) as the only - * parameter. +/** Type representing a handler function for events from the Desktop Agent + * or a PrivateChannel. + * @param event The handler function will be passed an `FDC3Event` or + * `PrivateChannelEvent` Object providing details of the event (such as a + * change of channel membership for the app, or type of context listener added) + * as the only parameter. */ -export type EventHandler = (event: FDC3Event) => void; +export type EventHandler = (event: FDC3Event | PrivateChannelEvent ) => void; /** * Enumeration defining the types of (non-context and non-intent) events that may be received @@ -19,8 +21,8 @@ export enum FDC3EventType { } /** - * Type representing the format of event objects that may be received - via the FDC3 API's `addEventListener` function. + * Type defining the format of event objects that may be received + via the FDC3 API's `addEventListener` function. */ export interface FDC3Event { readonly type: FDC3EventType; @@ -28,11 +30,73 @@ export interface FDC3Event { } /** - * Type representing the format of event USER_CHANNEL_CHANGED objects + * Type defining the format of event USER_CHANNEL_CHANGED objects */ export interface FDC3ChannelChangedEvent extends FDC3Event { readonly type: FDC3EventType.USER_CHANNEL_CHANGED; readonly details: { currentChannelId: string | null }; -} \ No newline at end of file +} + +/** + * Enumeration defining the types of events that may be received + via a PrivateChannel's `addEventListener` function. + */ + export enum PrivateChannelEventType { + ADD_CONTEXT_LISTENER = "addContextListener", + UNSUBSCRIBE = "unsubscribe", + DISCONNECT = "disconnect" +} + + +/** + * Type defining the format of event objects that may be received + * via a PrivateChannel's `addEventListener` function. + */ +export interface PrivateChannelEvent { + readonly type: PrivateChannelEventType; + readonly details: any; +} + +/** + * Type defining the format of events representing a context listener being + * added to the channel (`addContextListener`). Desktop Agents MUST fire this + * event for each invocation of `addContextListener` on the channel, including + * those that occurred before this handler was registered (to prevent race + * conditions). + * The context type of the listener added is provided as `details.contextType`, + * which will be `null` if all event types are being listened to. + */ +export interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent { + readonly type: PrivateChannelEventType.ADD_CONTEXT_LISTENER; + readonly details: { + contextType: string | null + }; +} + +/** + * Type defining the format of events representing a context listener + * removed from the channel (`Listener.unsubscribe()`). Desktop Agents MUST call + * this when `disconnect()` is called by the other party, for each listener that + * they had added. + * The context type of the listener removed is provided as `details.contextType`, + * which will be `null` if all event types were being listened to. + */ +export interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent { + readonly type: PrivateChannelEventType.UNSUBSCRIBE; + readonly details: { + contextType: string | null + }; +} + +/** + * Type defining the format of events representing a remote app being terminated + * or otherwise disconnecting from the PrivateChannel. This event is in addition to + * unsubscribe events that will also be fired for any context listeners they had added. + * No details are provided. + */ +export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent { + readonly type: PrivateChannelEventType.DISCONNECT; + readonly details: null | undefined; +} diff --git a/src/api/PrivateChannel.ts b/src/api/PrivateChannel.ts index a2036b21a..c8f4cb01a 100644 --- a/src/api/PrivateChannel.ts +++ b/src/api/PrivateChannel.ts @@ -5,6 +5,7 @@ import { Listener } from './Listener'; import { Channel } from './Channel'; +import { EventHandler, PrivateChannelEventType } from './Events'; /** * Object representing a private context channel, which is intended to support @@ -20,7 +21,47 @@ import { Channel } from './Channel'; * - MUST provide the `id` value for the channel as required by the Channel interface. */ export interface PrivateChannel extends Channel { + + /** + * Register a handler for events from the PrivateChannel. Whenever the handler function + * is called it will be passed an event object with details related to the event. + * + * ```js + * // any event type + * const listener = await myPrivateChannel.addEventListener(null, event => { + * console.log(`Received event ${event.type}\n\tDetails: ${event.details}`); + * }); + * + * // listener for a specific event type + * const channelChangedListener = await myPrivateChannel.addEventListener( + * PrivateChannelEventType.USER_CHANNEL_CHANGED, + * event => { ... } + * ); + * ``` + * + * @param {PrivateChannelEventType | null} type If non-null, only events of the specified type will be received by the handler. + * @param {EventHandler} handler A function that events received will be passed to. + * + */ + addEventListener(type: PrivateChannelEventType | null, handler: EventHandler): Promise; + + /** + * May be called to indicate that a participant will no longer interact with this channel. + * + * After this function has been called, Desktop Agents SHOULD prevent apps from broadcasting + * on this channel and MUST automatically call Listener.unsubscribe() for each listener that + * they've added (causing any onUnsubscribe handler added by the other party to be called) + * before triggering any onDisconnect handler added by the other party. + */ + disconnect(): Promise; + + //--------------------------------------------------------------------------------------------- + //Deprecated function signatures + //--------------------------------------------------------------------------------------------- + /** + * @deprecated use `addEventListener("addContextListener", handler)` instead. + * * Adds a listener that will be called each time that the remote app invokes * addContextListener on this channel. * @@ -31,6 +72,8 @@ export interface PrivateChannel extends Channel { onAddContextListener(handler: (contextType?: string) => void): Listener; /** + * @deprecated use `addEventListener("unsubscribe", handler)` instead. + * * Adds a listener that will be called whenever the remote app invokes * Listener.unsubscribe() on a context listener that it previously added. * @@ -40,19 +83,11 @@ export interface PrivateChannel extends Channel { onUnsubscribe(handler: (contextType?: string) => void): Listener; /** + * @deprecated use `addEventListener("disconnect", handler)` instead. + * * Adds a listener that will be called when the remote app terminates, for example * when its window is closed or because disconnect was called. This is in addition * to calls that will be made to onUnsubscribe listeners. */ onDisconnect(handler: () => void): Listener; - - /** - * May be called to indicate that a participant will no longer interact with this channel. - * - * After this function has been called, Desktop Agents SHOULD prevent apps from broadcasting - * on this channel and MUST automatically call Listener.unsubscribe() for each listener that - * they've added (causing any onUnsubscribe handler added by the other party to be called) - * before triggering any onDisconnect handler added by the other party. - */ - disconnect(): void; } From e72eabfde6d195b0401226b0f2397ba90e1d171a Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 2 Aug 2024 13:31:52 +0100 Subject: [PATCH 04/13] Changelog --- CHANGELOG.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 300247aaa..d7f416bb3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,16 +11,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added clarification that `id` field values SHOULD always be strings to context schema definition (a restriction that can't easily be represented in the generated types). ([#1149](https://github.com/finos/FDC3/pull/1149)) * Added requirement that Standard versions SHOULD avoid the use unions in context and API definitions wherever possible as these can be hard to replicate and MUST avoid unions of primitive types as these can be impossible to replicate in other languages. ([#120](https://github.com/finos/FDC3/pull/1200)) * Added `addEventListener` to the `DesktopAgent` API to provide support for event listener for non-context and non-intent events, including a USER_CHANNEL_CHANGED event ([#1207](https://github.com/finos/FDC3/pull/1207)) -* Added an `async` `addEventListener` function to the `PrivateChannel` API to replace the deprecated, synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions and to keep consistency with the DesktopAgent API. ([#X](https://github.com/finos/FDC3/pull/X)) +* Added an `async` `addEventListener` function to the `PrivateChannel` API to replace the deprecated, synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions and to keep consistency with the DesktopAgent API. ([#1305](https://github.com/finos/FDC3/pull/1305)) ### Changed -* `Listener.unsubscribe()` was made async (the return type was changed from `void` to `Promise`) for consistency with the rest of the API. ([#X](https://github.com/finos/FDC3/pull/X)) +* `Listener.unsubscribe()` was made async (the return type was changed from `void` to `Promise`) for consistency with the rest of the API. ([#1305](https://github.com/finos/FDC3/pull/1305)) ### Deprecated * Made `IntentMetadata.displayName` optional as it is deprecated. ([#1280](https://github.com/finos/FDC3/pull/1280)) -* Deprecated `PrivateChannel`'s synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions in favour of an `async` `addEventListener` function consistent with the one added to `DesktopAgent`. ([#X](https://github.com/finos/FDC3/pull/X)) +* Deprecated `PrivateChannel`'s synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions in favour of an `async` `addEventListener` function consistent with the one added to `DesktopAgent` in #1207. ([#1305](https://github.com/finos/FDC3/pull/1305)) ### Fixed From c47b7b2c38c40444360870f6c684d00524982cd2 Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 20 Aug 2024 12:51:02 +0100 Subject: [PATCH 05/13] Reworking addEventListener to avoid union types in .NET, events now inherit from a common ancestor ApiEvent --- docs/api/ref/DesktopAgent.md | 12 ++++-- docs/api/ref/Events.md | 69 ++++++++++++++++++++-------------- docs/api/ref/PrivateChannel.md | 7 ++-- src/api/DesktopAgent.ts | 4 +- src/api/Events.ts | 54 +++++++++++++------------- src/api/PrivateChannel.ts | 4 +- 6 files changed, 84 insertions(+), 66 deletions(-) diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index 204c12d3e..e0180ac68 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -41,7 +41,7 @@ interface DesktopAgent { leaveCurrentChannel() : Promise; // non-context events - addEventListener(type: FDC3EventType | null, handler: EventHandler): Promise; + addEventListener(type: FDC3EventTypes | null, handler: EventHandler): Promise; //implementation info getInfo(): Promise; @@ -96,7 +96,7 @@ const contactListener = await fdc3.addContextListener('fdc3.contact', (contact, ### `addEventListener` ```ts -addEventListener(type: FDC3EventType | null, handler: EventHandler): Promise; +addEventListener(type: FDC3EventTypes | null, handler: EventHandler): Promise; ``` Registers a handler for non-context and non-intent events from the Desktop Agent. If the consumer is only interested in an event of a particular type, they can specify that type. If the consumer is able to receive events of any type or will inspect types received, then they can pass `null` as the `type` parameter to receive all event types. @@ -110,13 +110,17 @@ Whenever the handler function is called it will be passed an event object with d const listener = await fdc3.addEventListener(null, event => { ... }); // listener for a specific event type that logs its details -const userChannelChangedListener = await fdc3.addEventListener(FDC3EventType.USER_CHANNEL_CHANGED, event => { +const userChannelChangedListener = await fdc3.addEventListener("USER_CHANNEL_CHANGED", event => { console.log(`Received event ${event.type}\n\tDetails: ${event.details}`); //do something else with the event }); -```` +``` +**See also:** +- [`FDC3EventTypes`](./Events#fdc3eventtypes) +- [`FDC3Event`](./Events#fdc3event) +- [`EventHandler`](./Events#eventhandler) ### `addIntentListener` diff --git a/docs/api/ref/Events.md b/docs/api/ref/Events.md index 276c99155..6bbb51bbb 100644 --- a/docs/api/ref/Events.md +++ b/docs/api/ref/Events.md @@ -4,10 +4,26 @@ title: Events In addition to intent and context events, the FDC3 API and PrivateChannel API may be used to listen for other types of events via their `addEventListener()` functions. +## `ApiEvent` + +Type defining a basic event object that may be emitted by an FDC3 API interface such as DesktopAgent or PrivateChannel. There are more specific event types defined for each interface. + +```ts +interface ApiEvent { + readonly type: string; + readonly details: any; +} +``` + +**See also:** + +- [`FDC3Event`](#fdc3event) +- [`PrivateChannelEvent`](#privatechannelevent) + ## `EventHandler` ```ts -type EventHandler = (event: FDC3Event | PrivateChannelEvent) => void; +type EventHandler = (event: ApiEvent) => void; ``` Describes a callback that handles non-context and non-intent events. Provides the details of the event. @@ -16,28 +32,27 @@ Used when attaching listeners to events. **See also:** -- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener) -- [`FDC3Event`](#fdc3event) +- [`DesktopAgent.addEventListener`](DesktopAgent#addeventlistener) +- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener) +- [`ApiEvent`](#apievent) -## `FDC3EventType` +## `FDC3EventTypes` ```ts -enum FDC3EventType { - USER_CHANNEL_CHANGED = "USER_CHANNEL_CHANGED" -} +type FDC3EventTypes = "USER_CHANNEL_CHANGED"; ``` -Enumeration defining the types of (non-context and non-intent) events that may be received via the FDC3 API's `addEventListener` function. +Type defining valid type strings for DesktopAgent interface events. **See also:** -- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener) +- [`DesktopAgent.addEventListener`](DesktopAgent#addeventlistener) ## `FDC3Event` ```ts -interface FDC3Event { - readonly type: FDC3EventType; +interface FDC3Event extends ApiEvent{ + readonly type: FDC3EventTypes; readonly details: any; } ``` @@ -48,14 +63,14 @@ Events will always include both `type` and `details` properties, which describe **See also:** -- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener) -- [`FDC3EventType`](#fdc3eventtype) +- [`DesktopAgent.addEventListener`](DesktopAgent#addeventlistener) +- [`FDC3EventTypes`](#fdc3eventtypes) ### `FDC3ChannelChangedEvent` ```ts interface FDC3ChannelChangedEvent extends FDC3Event { - readonly type: FDC3EventType.USER_CHANNEL_CHANGED; + readonly type: "USER_CHANNEL_CHANGED"; readonly details: { currentChannelId: string | null }; @@ -66,27 +81,23 @@ Type representing the format of USER_CHANNEL_CHANGED events. The identity of the channel joined is provided as `details.currentChannelId`, which will be `null` if the app is no longer joined to any channel. -## `PrivateChannelEventType` +## `PrivateChannelEventTypes` ```ts -enum PrivateChannelEventType { - ADD_CONTEXT_LISTENER = "addContextListener", - UNSUBSCRIBE = "unsubscribe", - DISCONNECT = "disconnect" -} +type PrivateChannelEventTypes = "addContextListener" | "unsubscribe" | "disconnect"; ``` -Enumeration defining the types of (non-context and non-intent) events that may be received via a PrivateChannel's `addEventListener` function. +Type defining valid type strings for Private Channel events. **See also:** -- [`PrivateChannel.addEventListener`](PrivateChannel#addEventListener) +- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener) ## `PrivateChannelEvent` ```ts -interface PrivateChannelEvent { - readonly type: PrivateChannelEventType; +interface PrivateChannelEvent extends ApiEvent { + readonly type: PrivateChannelEventTypes; readonly details: any; } ``` @@ -95,14 +106,14 @@ Type defining the format of event objects that may be received via a PrivateChan **See also:** -- [`PrivateChannel.addEventListener`](PrivateChannel#addEventListener) -- [`PrivateChannelEventType`](#privatechanneleventtype) +- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener) +- [`PrivateChannelEventTypes`](#privatechanneleventtypes) ### `PrivateChannelAddContextListenerEvent` ```ts interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent { - readonly type: PrivateChannelEventType.ADD_CONTEXT_LISTENER; + readonly type: "addContextListener"; readonly details: { contextType: string | null }; @@ -117,7 +128,7 @@ The context type of the listener added is provided as `details.contextType`, whi ```ts interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent { - readonly type: PrivateChannelEventType.UNSUBSCRIBE; + readonly type: "unsubscribe"; readonly details: { contextType: string | null }; @@ -132,7 +143,7 @@ The context type of the listener removed is provided as `details.contextType`, ```ts export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent { - readonly type: PrivateChannelEventType.DISCONNECT; + readonly type: "disconnect"; readonly details: null | undefined; } ``` diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index 5c2024665..66b558cd1 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -17,7 +17,7 @@ It is intended that Desktop Agent implementations: ```ts interface PrivateChannel extends Channel { // functions - addEventListener(type: PrivateChannelEventType | null, handler: EventHandler): Promise; + addEventListener(type: PrivateChannelEventTypes | null, handler: EventHandler): Promise; disconnect(): Promise; //deprecated functions @@ -120,7 +120,7 @@ try { ### `addEventListener` ```ts -addEventListener(type: PrivateChannelEventType | null, handler: EventHandler): Promise; +addEventListener(type: PrivateChannelEventTypes | null, handler: EventHandler): Promise; ``` Register a handler for events from the PrivateChannel. Whenever the handler function is called it will be passed an event object with details related to the event. @@ -142,7 +142,8 @@ const channelChangedListener: Listener = await myPrivateChannel.addEventListener **See also:** -- [`PrivateChannelEventType`](./Events#privatechanneleventtype) +- [`PrivateChannelEventTypes`](./Events#privatechanneleventtypes) +- [`PrivateChannelEvent`](./Events#privatechannelevent) - [`EventHandler`](./Events#eventhandler) ### `disconnect` diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index 59be809df..1ea47a205 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -15,7 +15,7 @@ import { AppIdentifier } from './AppIdentifier'; import { AppMetadata } from './AppMetadata'; import { Intent } from '../intents/Intents'; import { ContextType } from '../context/ContextType'; -import { EventHandler, FDC3EventType } from './Events'; +import { EventHandler, FDC3EventTypes } from './Events'; /** * A Desktop Agent is a desktop component (or aggregate of components) that serves as a @@ -395,7 +395,7 @@ export interface DesktopAgent { * @param {EventHandler} handler A function that events received will be passed to. * */ - addEventListener(type: FDC3EventType | null, handler: EventHandler): Promise; + addEventListener(type: FDC3EventTypes | null, handler: EventHandler): Promise; /** * Retrieves a list of the User channels available for the app to join. diff --git a/src/api/Events.ts b/src/api/Events.ts index 71fef0b37..b919890ad 100644 --- a/src/api/Events.ts +++ b/src/api/Events.ts @@ -3,29 +3,37 @@ * Copyright FINOS FDC3 contributors - see NOTICE file */ +/** + * Type defining a basic event object that may be emitted by an FDC3 API interface + * such as DesktopAgent or PrivateChannel. There are more specific event types + * defined for each interface. + */ +export interface ApiEvent { + readonly type: string; + readonly details: any; +} + /** Type representing a handler function for events from the Desktop Agent * or a PrivateChannel. - * @param event The handler function will be passed an `FDC3Event` or - * `PrivateChannelEvent` Object providing details of the event (such as a - * change of channel membership for the app, or type of context listener added) + * @param event The handler function will be passed an `ApiEvent` (or more specifically + * an `FDC3Event` or `PrivateChannelEvent`) Object providing details of the event (such + * as a change of channel membership for the app, or type of context listener added) * as the only parameter. */ -export type EventHandler = (event: FDC3Event | PrivateChannelEvent ) => void; +export type EventHandler = (event: ApiEvent ) => void; /** - * Enumeration defining the types of (non-context and non-intent) events that may be received - via the FDC3 API's `addEventListener` function. + * Type defining valid type strings for DesktopAgent interface events. */ -export enum FDC3EventType { - USER_CHANNEL_CHANGED = "USER_CHANNEL_CHANGED" -} +export type FDC3EventTypes = "USER_CHANNEL_CHANGED"; + /** * Type defining the format of event objects that may be received - via the FDC3 API's `addEventListener` function. + * via the FDC3 API's `addEventListener` function. */ -export interface FDC3Event { - readonly type: FDC3EventType; +export interface FDC3Event extends ApiEvent { + readonly string: FDC3EventTypes; readonly details: any; } @@ -33,29 +41,23 @@ export interface FDC3Event { * Type defining the format of event USER_CHANNEL_CHANGED objects */ export interface FDC3ChannelChangedEvent extends FDC3Event { - readonly type: FDC3EventType.USER_CHANNEL_CHANGED; + readonly type: "USER_CHANNEL_CHANGED"; readonly details: { currentChannelId: string | null }; } /** - * Enumeration defining the types of events that may be received - via a PrivateChannel's `addEventListener` function. + * Type defining valid type strings for Private Channel events. */ - export enum PrivateChannelEventType { - ADD_CONTEXT_LISTENER = "addContextListener", - UNSUBSCRIBE = "unsubscribe", - DISCONNECT = "disconnect" -} - - +export type PrivateChannelEventTypes = "addContextListener" | "unsubscribe" | "disconnect"; + /** * Type defining the format of event objects that may be received * via a PrivateChannel's `addEventListener` function. */ export interface PrivateChannelEvent { - readonly type: PrivateChannelEventType; + readonly type: PrivateChannelEventTypes; readonly details: any; } @@ -69,7 +71,7 @@ export interface PrivateChannelEvent { * which will be `null` if all event types are being listened to. */ export interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent { - readonly type: PrivateChannelEventType.ADD_CONTEXT_LISTENER; + readonly type: "addContextListener"; readonly details: { contextType: string | null }; @@ -84,7 +86,7 @@ export interface PrivateChannelAddContextListenerEvent extends PrivateChannelEve * which will be `null` if all event types were being listened to. */ export interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent { - readonly type: PrivateChannelEventType.UNSUBSCRIBE; + readonly type: "unsubscribe"; readonly details: { contextType: string | null }; @@ -97,6 +99,6 @@ export interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent { * No details are provided. */ export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent { - readonly type: PrivateChannelEventType.DISCONNECT; + readonly type: "disconnect"; readonly details: null | undefined; } diff --git a/src/api/PrivateChannel.ts b/src/api/PrivateChannel.ts index c8f4cb01a..6a2444361 100644 --- a/src/api/PrivateChannel.ts +++ b/src/api/PrivateChannel.ts @@ -5,7 +5,7 @@ import { Listener } from './Listener'; import { Channel } from './Channel'; -import { EventHandler, PrivateChannelEventType } from './Events'; +import { EventHandler, PrivateChannelEventTypes } from './Events'; /** * Object representing a private context channel, which is intended to support @@ -43,7 +43,7 @@ export interface PrivateChannel extends Channel { * @param {EventHandler} handler A function that events received will be passed to. * */ - addEventListener(type: PrivateChannelEventType | null, handler: EventHandler): Promise; + addEventListener(type: PrivateChannelEventTypes | null, handler: EventHandler): Promise; /** * May be called to indicate that a participant will no longer interact with this channel. From 8654cbe14680cd4a36521342a127d739a184229f Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 23 Aug 2024 12:03:54 +0100 Subject: [PATCH 06/13] Make event type names style consistent (camelCase) --- CHANGELOG.md | 2 +- docs/api/ref/DesktopAgent.md | 2 +- docs/api/ref/Events.md | 6 ++-- src/api/DesktopAgent.ts | 2 +- src/api/Events.ts | 6 ++-- src/api/PrivateChannel.ts | 2 +- src/context/ContextTypes.ts | 60 ++++++++++++++++++------------------ 7 files changed, 40 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d7f416bb3..db1d19374 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added clarification that `id` field values SHOULD always be strings to context schema definition (a restriction that can't easily be represented in the generated types). ([#1149](https://github.com/finos/FDC3/pull/1149)) * Added requirement that Standard versions SHOULD avoid the use unions in context and API definitions wherever possible as these can be hard to replicate and MUST avoid unions of primitive types as these can be impossible to replicate in other languages. ([#120](https://github.com/finos/FDC3/pull/1200)) -* Added `addEventListener` to the `DesktopAgent` API to provide support for event listener for non-context and non-intent events, including a USER_CHANNEL_CHANGED event ([#1207](https://github.com/finos/FDC3/pull/1207)) +* Added `addEventListener` to the `DesktopAgent` API to provide support for event listener for non-context and non-intent events, including a `userChannelChanged` event ([#1207](https://github.com/finos/FDC3/pull/1207)) * Added an `async` `addEventListener` function to the `PrivateChannel` API to replace the deprecated, synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions and to keep consistency with the DesktopAgent API. ([#1305](https://github.com/finos/FDC3/pull/1305)) ### Changed diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md index e0180ac68..ed47ab800 100644 --- a/docs/api/ref/DesktopAgent.md +++ b/docs/api/ref/DesktopAgent.md @@ -110,7 +110,7 @@ Whenever the handler function is called it will be passed an event object with d const listener = await fdc3.addEventListener(null, event => { ... }); // listener for a specific event type that logs its details -const userChannelChangedListener = await fdc3.addEventListener("USER_CHANNEL_CHANGED", event => { +const userChannelChangedListener = await fdc3.addEventListener("userChannelChanged ", event => { console.log(`Received event ${event.type}\n\tDetails: ${event.details}`); //do something else with the event }); diff --git a/docs/api/ref/Events.md b/docs/api/ref/Events.md index 6bbb51bbb..3eb89230c 100644 --- a/docs/api/ref/Events.md +++ b/docs/api/ref/Events.md @@ -39,7 +39,7 @@ Used when attaching listeners to events. ## `FDC3EventTypes` ```ts -type FDC3EventTypes = "USER_CHANNEL_CHANGED"; +type FDC3EventTypes = "userChannelChanged"; ``` Type defining valid type strings for DesktopAgent interface events. @@ -70,14 +70,14 @@ Events will always include both `type` and `details` properties, which describe ```ts interface FDC3ChannelChangedEvent extends FDC3Event { - readonly type: "USER_CHANNEL_CHANGED"; + readonly type: "userChannelChanged"; readonly details: { currentChannelId: string | null }; } ``` -Type representing the format of USER_CHANNEL_CHANGED events. +Type representing the format of `userChannelChanged` events. The identity of the channel joined is provided as `details.currentChannelId`, which will be `null` if the app is no longer joined to any channel. diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts index 1ea47a205..b31289d74 100644 --- a/src/api/DesktopAgent.ts +++ b/src/api/DesktopAgent.ts @@ -385,7 +385,7 @@ export interface DesktopAgent { * const listener = await fdc3.addEventListener(null, event => { ... }); * * // listener for a specific event type that logs its details - * const userChannelChangedListener = await fdc3.addEventListener(FDC3EventType.USER_CHANNEL_CHANGED, event => { + * const userChannelChangedListener = await fdc3.addEventListener("userChannelChanged", event => { * console.log(`Received event ${event.type}\n\tDetails: ${event.details}`); * //do something else with the event * }); diff --git a/src/api/Events.ts b/src/api/Events.ts index b919890ad..bf507d74f 100644 --- a/src/api/Events.ts +++ b/src/api/Events.ts @@ -25,7 +25,7 @@ export type EventHandler = (event: ApiEvent ) => void; /** * Type defining valid type strings for DesktopAgent interface events. */ -export type FDC3EventTypes = "USER_CHANNEL_CHANGED"; +export type FDC3EventTypes = "userChannelChanged"; /** @@ -38,10 +38,10 @@ export interface FDC3Event extends ApiEvent { } /** - * Type defining the format of event USER_CHANNEL_CHANGED objects + * Type defining the format of event `userChannelChanged` objects */ export interface FDC3ChannelChangedEvent extends FDC3Event { - readonly type: "USER_CHANNEL_CHANGED"; + readonly type: "userChannelChanged"; readonly details: { currentChannelId: string | null }; diff --git a/src/api/PrivateChannel.ts b/src/api/PrivateChannel.ts index 6a2444361..f9a15fa09 100644 --- a/src/api/PrivateChannel.ts +++ b/src/api/PrivateChannel.ts @@ -34,7 +34,7 @@ export interface PrivateChannel extends Channel { * * // listener for a specific event type * const channelChangedListener = await myPrivateChannel.addEventListener( - * PrivateChannelEventType.USER_CHANNEL_CHANGED, + * "addContextListener", * event => { ... } * ); * ``` diff --git a/src/context/ContextTypes.ts b/src/context/ContextTypes.ts index 8b8c0d45a..8fccd9007 100644 --- a/src/context/ContextTypes.ts +++ b/src/context/ContextTypes.ts @@ -258,35 +258,35 @@ export interface InstrumentElement { */ export interface PurpleInstrumentIdentifiers { /** - * + * https://www.bloomberg.com/ */ BBG?: string; /** - * + * https://www.cusip.com/ */ CUSIP?: string; /** - * + * https://www.factset.com/ */ FDS_ID?: string; /** - * + * https://www.openfigi.com/ */ FIGI?: string; /** - * + * https://www.isin.org/ */ ISIN?: string; /** - * + * https://permid.org/ */ PERMID?: string; /** - * + * https://www.refinitiv.com/ */ RIC?: string; /** - * + * https://www.lseg.com/sedol */ SEDOL?: string; /** @@ -303,15 +303,15 @@ export interface PurpleInstrumentIdentifiers { */ export interface OrganizationMarket { /** - * + * https://www.bloomberg.com/ */ BBG?: string; /** - * + * https://www.iso.org/iso-3166-country-codes.html */ COUNTRY_ISOALPHA2?: string; /** - * + * https://en.wikipedia.org/wiki/Market_Identifier_Code */ MIC?: string; /** @@ -798,15 +798,15 @@ export interface OrganizationObject { */ export interface Identifiers { /** - * + * https://www.bloomberg.com/ */ BBG?: string; /** - * + * https://www.cusip.com/ */ CUSIP?: string; /** - * + * https://www.factset.com/ * * FactSet Permanent Identifier representing the organization * @@ -814,25 +814,25 @@ export interface Identifiers { */ FDS_ID?: string; /** - * + * https://www.openfigi.com/ */ FIGI?: string; /** - * + * https://www.isin.org/ */ ISIN?: string; /** - * + * https://permid.org/ * * Refinitiv Permanent Identifiers, or PermID for the organization */ PERMID?: string; /** - * + * https://www.refinitiv.com/ */ RIC?: string; /** - * + * https://www.lseg.com/sedol */ SEDOL?: string; /** @@ -1181,35 +1181,35 @@ export interface Instrument { */ export interface FluffyInstrumentIdentifiers { /** - * + * https://www.bloomberg.com/ */ BBG?: string; /** - * + * https://www.cusip.com/ */ CUSIP?: string; /** - * + * https://www.factset.com/ */ FDS_ID?: string; /** - * + * https://www.openfigi.com/ */ FIGI?: string; /** - * + * https://www.isin.org/ */ ISIN?: string; /** - * + * https://permid.org/ */ PERMID?: string; /** - * + * https://www.refinitiv.com/ */ RIC?: string; /** - * + * https://www.lseg.com/sedol */ SEDOL?: string; /** @@ -1226,15 +1226,15 @@ export interface FluffyInstrumentIdentifiers { */ export interface PurpleMarket { /** - * + * https://www.bloomberg.com/ */ BBG?: string; /** - * + * https://www.iso.org/iso-3166-country-codes.html */ COUNTRY_ISOALPHA2?: string; /** - * + * https://en.wikipedia.org/wiki/Market_Identifier_Code */ MIC?: string; /** From 5719b3344108470887fb052e8c4f8cbfe7be243c Mon Sep 17 00:00:00 2001 From: Kris West Date: Mon, 2 Sep 2024 16:58:58 +0100 Subject: [PATCH 07/13] typo identified in code review --- docs/api/ref/PrivateChannel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index 66b558cd1..42c79cf5b 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -188,6 +188,6 @@ Adds a listener that will be called whenever the remote app invokes `Listener.un onDisconnect(handler: () => void): Listener; ``` -Deprecated in favour of the aysnc `addEventListener("disconnect", handler)` function. +Deprecated in favour of the async `addEventListener("disconnect", handler)` function. Adds a listener that will be called when the remote app terminates, for example when its window is closed or because disconnect was called. From 9e3bf098b1958a4eefd5b73d6ed7c87b5b6e2793 Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 3 Sep 2024 12:28:14 +0100 Subject: [PATCH 08/13] fix syntax error on tabs --- docs/api/ref/PrivateChannel.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index ba219695b..081af8873 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -68,9 +68,9 @@ The Desktop Agent knows that a channel is being returned by inspecting the objec Although this interaction occurs entirely in frontend code, we refer to it as the 'server-side' interaction as it receives a request and initiates a stream of responses. - + ```ts fdc3.addIntentListener("QuoteStream", async (context) => { const channel: PrivateChannel = await fdc3.createPrivateChannel(); @@ -178,6 +178,7 @@ try { console.error(`Error: Intent was not resolved: ${resolverError}`); } ``` + From 889852da59b0024f130664f887693ec66a830978 Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 3 Sep 2024 12:35:55 +0100 Subject: [PATCH 09/13] fixing another syntax issue --- docs/api/ref/PrivateChannel.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index 081af8873..e7ee3b889 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -229,8 +229,21 @@ catch (Exception ex) addEventListener(type: PrivateChannelEventTypes | null, handler: EventHandler): Promise; ``` + + + +```csharp +Not implemented +``` + + + + Register a handler for events from the PrivateChannel. Whenever the handler function is called it will be passed an event object with details related to the event. + + + ```ts // any event type const listener: Listener = await myPrivateChannel.addEventListener(null, @@ -239,17 +252,17 @@ const listener: Listener = await myPrivateChannel.addEventListener(null, } ); ``` - + -``` +```csharp Not implemented ``` - + **See also:** - [Events](./Events) @@ -277,7 +290,6 @@ void Disconnect(); May be called to indicate that a participant will no longer interact with this channel. - ## Deprecated Functions ### `onAddContextListener` From 32722dc123401500d4bb5de8b8f30ba5cd640541 Mon Sep 17 00:00:00 2001 From: Kris West Date: Tue, 3 Sep 2024 12:50:19 +0100 Subject: [PATCH 10/13] more syntax errors - still one present I can't find --- docs/api/ref/PrivateChannel.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index e7ee3b889..51df91acc 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -62,7 +62,7 @@ interface IPrivateChannel : IChannel, IIntentResult ### 'Server-side' example -The intent app establishes and returns a `PrivateChannel` to the client (who is awaiting `getResult()`). When the client calls `addContextlistener()` on that channel, the intent app receives notice via the handler added with `addEventListener()` and knows that the client is ready to start receiving quotes. +The intent app establishes and returns a `PrivateChannel` to the client (who is awaiting `getResult()`). When the client calls `addContextListener()` on that channel, the intent app receives notice via the handler added with `addEventListener()` and knows that the client is ready to start receiving quotes. The Desktop Agent knows that a channel is being returned by inspecting the object returned from the handler (e.g. check constructor or look for private member). @@ -268,9 +268,9 @@ Not implemented - [Events](./Events) - [EventHandler](./Events#eventhandler) - [PrivateChannelEvent](./Events#privatechannelevent) -- [PrivateChannelAddContextListenerEvent]](./Events#privatechanneladdcontextlistenerevent) -- [PrivateChannelUnsubscribeEvent]](./Events#privatechannelunsubscribeevent) -- [PrivateChannelDisconnectEvent]](./Events#privatechanneldisconnectevent) +- [PrivateChannelAddContextListenerEvent](./Events#privatechanneladdcontextlistenerevent) +- [PrivateChannelUnsubscribeEvent](./Events#privatechannelunsubscribeevent) +- [PrivateChannelDisconnectEvent](./Events#privatechanneldisconnectevent) ### `disconnect` @@ -287,6 +287,9 @@ disconnect(): Promise; ```csharp void Disconnect(); ``` + + + May be called to indicate that a participant will no longer interact with this channel. @@ -296,18 +299,18 @@ May be called to indicate that a participant will no longer interact with this c - + ```ts onAddContextListener(handler: (contextType?: string) => void): Listener; ``` - + ```csharp IListener OnAddContextListener(Action handler); ``` - + @@ -359,4 +362,4 @@ IListener OnDisconnect(Action handler); Deprecated in favour of the async `addEventListener("disconnect", handler)` function. -Adds a listener that will be called when the remote app terminates, for example when its window is closed or because disconnect was called. \ No newline at end of file +Adds a listener that will be called when the remote app terminates, for example when its window is closed or because disconnect was called. From 4f027b8c2a2aaa0cc3f9e35aceb68bd1255c774f Mon Sep 17 00:00:00 2001 From: bingenito <28159742+bingenito@users.noreply.github.com> Date: Wed, 4 Sep 2024 07:13:48 -0400 Subject: [PATCH 11/13] Remove spaces in OnUnsubscribe csharp markdown --- docs/api/ref/PrivateChannel.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index 51df91acc..ccb03625f 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -329,11 +329,11 @@ onUnsubscribe(handler: (contextType?: string) => void): Listener; - + ```csharp IListener OnUnsubscribe(Action handler); ``` - + From a07e77639102e71ef5fbeecdb2cef532df822419 Mon Sep 17 00:00:00 2001 From: bingenito <28159742+bingenito@users.noreply.github.com> Date: Wed, 4 Sep 2024 08:16:39 -0400 Subject: [PATCH 12/13] Remove extra spaces on Disconnect and OnDisconnect --- docs/api/ref/PrivateChannel.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index ccb03625f..2e58e517b 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -283,7 +283,7 @@ disconnect(): Promise; - + ```csharp void Disconnect(); ``` @@ -352,11 +352,11 @@ onDisconnect(handler: () => void): Listener; - + ```csharp IListener OnDisconnect(Action handler); ``` - + From 2ed30e60bbcee8250e2b996044e71c2f29dd34c1 Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 5 Sep 2024 14:54:13 +0100 Subject: [PATCH 13/13] stray space chars --- docs/api/ref/PrivateChannel.md | 4 ++-- docs/context/ref/ChatRoom.md | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api/ref/PrivateChannel.md b/docs/api/ref/PrivateChannel.md index 2e58e517b..300ff0439 100644 --- a/docs/api/ref/PrivateChannel.md +++ b/docs/api/ref/PrivateChannel.md @@ -345,11 +345,11 @@ Adds a listener that will be called whenever the remote app invokes `Listener.un - + ```ts onDisconnect(handler: () => void): Listener; ``` - + diff --git a/docs/context/ref/ChatRoom.md b/docs/context/ref/ChatRoom.md index 14a5924a5..fbd2d8c04 100644 --- a/docs/context/ref/ChatRoom.md +++ b/docs/context/ref/ChatRoom.md @@ -1,6 +1,7 @@ --- title: ChatRoom sidebar_label: ChatRoom + --- # ChatRoom