From 19a3aad26f882493be62bbfd44c8346152126854 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 15 Jan 2025 18:46:02 +0000 Subject: [PATCH 1/6] Adding support for controlling debug logging in fdc3-agent-proxy and fdc3-get-agent --- .../fdc3-agent-proxy/src/DesktopAgentProxy.ts | 13 +- .../src/apps/DefaultAppSupport.ts | 5 +- .../src/channels/DefaultChannelSupport.ts | 7 +- packages/fdc3-agent-proxy/src/index.ts | 2 + .../src/intents/DefaultIntentSupport.ts | 2 +- .../src/listeners/AbstractListener.ts | 2 +- .../src/listeners/HeartbeatListener.ts | 2 + .../listeners/PrivateChannelEventListener.ts | 7 +- .../src/messaging/AbstractMessaging.ts | 5 +- .../src/util/AbstractFDC3Logger.ts | 89 + packages/fdc3-agent-proxy/src/util/Logger.ts | 19 + .../src/{util.ts => util/throwIfUndefined.ts} | 3 +- .../test/features/utils.feature | 4 + .../step-definitions/channelSelector.steps.ts | 2 +- .../test/step-definitions/generic.steps.ts | 2 +- .../test/step-definitions/util.steps.ts | 25 +- .../src/messaging/message-port.ts | 8 +- .../src/strategies/FailoverHandler.ts | 10 +- .../src/strategies/PostMessageLoader.ts | 12 +- .../fdc3-get-agent/src/strategies/getAgent.ts | 8 +- packages/fdc3-get-agent/src/util/Logger.ts | 62 +- .../test/step-definitions/util.steps.ts | 16 +- .../fdc3-schema/generated/api/BrowserTypes.ts | 5316 ++++++++--------- packages/fdc3-standard/src/api/GetAgent.ts | 30 + website/docs/api/ref/GetAgent.md | 42 +- 25 files changed, 2940 insertions(+), 2753 deletions(-) create mode 100644 packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts create mode 100644 packages/fdc3-agent-proxy/src/util/Logger.ts rename packages/fdc3-agent-proxy/src/{util.ts => util/throwIfUndefined.ts} (84%) diff --git a/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts b/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts index 1a8c80838..a3d903a7c 100644 --- a/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts +++ b/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts @@ -16,6 +16,12 @@ import { IntentSupport } from './intents/IntentSupport'; import { Connectable, Channel } from '@finos/fdc3-standard'; import { Context } from '@finos/fdc3-context'; import { HeartbeatSupport } from './heartbeat/HeartbeatSupport'; +import { Logger } from './util/Logger'; + +export type DesktopAgentProxyLogSettings = { + heartbeat: boolean; + debug: boolean; +}; /** * This splits out the functionality of the desktop agent into @@ -33,13 +39,16 @@ export class DesktopAgentProxy implements DesktopAgent, Connectable { channels: ChannelSupport, intents: IntentSupport, apps: AppSupport, - connectables: Connectable[] + connectables: Connectable[], + logging: DesktopAgentProxyLogSettings ) { this.heartbeat = heartbeat; this.intents = intents; this.channels = channels; this.apps = apps; this.connectables = connectables; + Logger.enableHeartbeatLogs(logging.heartbeat); + Logger.enableDebugLogs(logging.debug); } addEventListener(type: FDC3EventTypes | null, handler: EventHandler): Promise { @@ -47,7 +56,7 @@ export class DesktopAgentProxy implements DesktopAgent, Connectable { case 'userChannelChanged': return this.channels.addChannelChangedEventHandler(handler); default: - console.warn(`Tried to add a listener for an unknown event type: ${type}`); + Logger.warn(`Tried to add a listener for an unknown event type: ${type}`); return Promise.reject(new Error('UnknownEventType')); } } diff --git a/packages/fdc3-agent-proxy/src/apps/DefaultAppSupport.ts b/packages/fdc3-agent-proxy/src/apps/DefaultAppSupport.ts index 0b38144b4..03439dbd5 100644 --- a/packages/fdc3-agent-proxy/src/apps/DefaultAppSupport.ts +++ b/packages/fdc3-agent-proxy/src/apps/DefaultAppSupport.ts @@ -12,7 +12,8 @@ import { OpenRequest, OpenResponse, } from '@finos/fdc3-schema/generated/api/BrowserTypes'; -import { throwIfUndefined } from '../util'; +import { throwIfUndefined } from '../util/throwIfUndefined'; +import { Logger } from '../util/Logger'; export class DefaultAppSupport implements AppSupport { readonly messaging: Messaging; @@ -96,7 +97,7 @@ export class DefaultAppSupport implements AppSupport { return response.payload.implementationMetadata; } else { //This will only happen if the DA implementation returns an invalid message with a missing implementationMetadata property - console.error('Invalid response from Desktop Agent to open!', response); + Logger.error('Invalid response from Desktop Agent to open!', response); const unknownImpl: ImplementationMetadata = { fdc3Version: 'unknown', provider: 'unknown', diff --git a/packages/fdc3-agent-proxy/src/channels/DefaultChannelSupport.ts b/packages/fdc3-agent-proxy/src/channels/DefaultChannelSupport.ts index a73c199ae..85ba2b0f2 100644 --- a/packages/fdc3-agent-proxy/src/channels/DefaultChannelSupport.ts +++ b/packages/fdc3-agent-proxy/src/channels/DefaultChannelSupport.ts @@ -28,7 +28,8 @@ import { JoinUserChannelResponse, JoinUserChannelRequest, } from '@finos/fdc3-schema/generated/api/BrowserTypes'; -import { throwIfUndefined } from '../util'; +import { throwIfUndefined } from '../util/throwIfUndefined'; +import { Logger } from '../util/Logger'; export class DefaultChannelSupport implements ChannelSupport { readonly messaging: Messaging; @@ -40,7 +41,7 @@ export class DefaultChannelSupport implements ChannelSupport { this.messaging = messaging; this.channelSelector = channelSelector; this.channelSelector.setChannelChangeCallback((channelId: string | null) => { - console.debug('Channel selector reports channel changed: ' + channelId); + Logger.debug('Channel selector reports channel changed: ', channelId); if (channelId == null) { this.leaveUserChannel(); } else { @@ -49,6 +50,7 @@ export class DefaultChannelSupport implements ChannelSupport { }); this.addChannelChangedEventHandler(e => { + Logger.debug('Desktop Agent reports channel changed: ', e.details.newChannelId); this.channelSelector.updateChannel(e.details.newChannelId, this.userChannels); }); } @@ -177,7 +179,6 @@ export class DefaultChannelSupport implements ChannelSupport { } async addContextListener(handler: ContextHandler, type: string | null): Promise { - //TODO: Figure out a better solution than inlining this class. /** Utility class used to wrap the DefaultContextListener and ensure it gets removed * when its unsubscribe function is called. */ diff --git a/packages/fdc3-agent-proxy/src/index.ts b/packages/fdc3-agent-proxy/src/index.ts index 19955f2e2..df1207355 100644 --- a/packages/fdc3-agent-proxy/src/index.ts +++ b/packages/fdc3-agent-proxy/src/index.ts @@ -11,6 +11,7 @@ import { DefaultAppSupport } from './apps/DefaultAppSupport'; import { AppSupport } from './apps/AppSupport'; import { DefaultHeartbeatSupport } from './heartbeat/DefaultHeartbeatSupport'; import { Connectable } from '@finos/fdc3-standard'; +import { AbstractFDC3Logger } from './util/AbstractFDC3Logger'; export { type Messaging, @@ -26,4 +27,5 @@ export { DefaultHeartbeatSupport, RegisterableListener, Connectable, + AbstractFDC3Logger, }; diff --git a/packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts b/packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts index 1ab99d109..2b39437b6 100644 --- a/packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts +++ b/packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts @@ -27,7 +27,7 @@ import { RaiseIntentResponse, RaiseIntentResultResponse, } from '@finos/fdc3-schema/generated/api/BrowserTypes'; -import { throwIfUndefined } from '../util'; +import { throwIfUndefined } from '../util/throwIfUndefined'; const convertIntentResult = async ( { payload }: RaiseIntentResultResponse, diff --git a/packages/fdc3-agent-proxy/src/listeners/AbstractListener.ts b/packages/fdc3-agent-proxy/src/listeners/AbstractListener.ts index aaceae29e..4153a2f3f 100644 --- a/packages/fdc3-agent-proxy/src/listeners/AbstractListener.ts +++ b/packages/fdc3-agent-proxy/src/listeners/AbstractListener.ts @@ -19,7 +19,7 @@ import { } from '@finos/fdc3-schema/generated/api/BrowserTypes'; import { Messaging } from '../Messaging'; import { RegisterableListener } from './RegisterableListener'; -import { throwIfUndefined } from '../util'; +import { throwIfUndefined } from '../util/throwIfUndefined'; import { ChannelError } from '@finos/fdc3-standard'; type SubscriptionRequest = diff --git a/packages/fdc3-agent-proxy/src/listeners/HeartbeatListener.ts b/packages/fdc3-agent-proxy/src/listeners/HeartbeatListener.ts index ab7878dc8..f04191694 100644 --- a/packages/fdc3-agent-proxy/src/listeners/HeartbeatListener.ts +++ b/packages/fdc3-agent-proxy/src/listeners/HeartbeatListener.ts @@ -5,6 +5,7 @@ import { } from '@finos/fdc3-schema/generated/api/BrowserTypes'; import { Messaging } from '../Messaging'; import { RegisterableListener } from './RegisterableListener'; +import { Logger } from '../util/Logger'; export class HeartbeatListener implements RegisterableListener { readonly id: string; @@ -20,6 +21,7 @@ export class HeartbeatListener implements RegisterableListener { } action(_m: AgentEventMessage): void { + Logger.heartbeatLog('Responding to heartbeat request', _m); const request: HeartbeatAcknowledgementRequest = { type: 'heartbeatAcknowledgementRequest', meta: { diff --git a/packages/fdc3-agent-proxy/src/listeners/PrivateChannelEventListener.ts b/packages/fdc3-agent-proxy/src/listeners/PrivateChannelEventListener.ts index 80fbfe272..77cb08710 100644 --- a/packages/fdc3-agent-proxy/src/listeners/PrivateChannelEventListener.ts +++ b/packages/fdc3-agent-proxy/src/listeners/PrivateChannelEventListener.ts @@ -10,6 +10,7 @@ import { PrivateChannelUnsubscribeEvent, } from '@finos/fdc3-standard'; import { BrowserTypes } from '@finos/fdc3-schema'; +import { Logger } from '../util/Logger'; const { isPrivateChannelOnAddContextListenerEvent, isPrivateChannelOnDisconnectEvent, @@ -116,7 +117,7 @@ export class PrivateChannelDisconnectEventListener extends AbstractPrivateChanne }; handler(event); } else { - console.error('PrivateChannelDisconnectEventListener was called for a different message type!', msg); + Logger.error('PrivateChannelDisconnectEventListener was called for a different message type!', msg); } }; @@ -134,7 +135,7 @@ export class PrivateChannelAddContextEventListener extends AbstractPrivateChanne }; handler(event); } else { - console.error('PrivateChannelAddContextEventListener was called for a different message type!', msg); + Logger.error('PrivateChannelAddContextEventListener was called for a different message type!', msg); } }; super(messaging, channelId, ['privateChannelOnAddContextListenerEvent'], 'addContextListener', wrappedHandler); @@ -151,7 +152,7 @@ export class PrivateChannelUnsubscribeEventListener extends AbstractPrivateChann }; handler(event); } else { - console.error('PrivateChannelUnsubscribeEventListener was called for a different message type!', msg); + Logger.error('PrivateChannelUnsubscribeEventListener was called for a different message type!', msg); } }; super(messaging, channelId, ['privateChannelOnUnsubscribeEvent'], 'unsubscribe', wrappedHandler); diff --git a/packages/fdc3-agent-proxy/src/messaging/AbstractMessaging.ts b/packages/fdc3-agent-proxy/src/messaging/AbstractMessaging.ts index b79cc0e58..1c9f6d0db 100644 --- a/packages/fdc3-agent-proxy/src/messaging/AbstractMessaging.ts +++ b/packages/fdc3-agent-proxy/src/messaging/AbstractMessaging.ts @@ -6,6 +6,7 @@ import { AppRequestMessage, WebConnectionProtocol6Goodbye, } from '@finos/fdc3-schema/generated/api/BrowserTypes'; +import { Logger } from '../util/Logger'; export abstract class AbstractMessaging implements Messaging { private appIdentifier: AppIdentifier; @@ -30,6 +31,7 @@ export abstract class AbstractMessaging implements Messaging { id, filter: filter, action: m => { + Logger.debug('Received from DesktopAgent: ', m); done = true; this.unregister(id); if (timeout) { @@ -51,7 +53,7 @@ export abstract class AbstractMessaging implements Messaging { timeout = setTimeout(() => { this.unregister(id); if (!done) { - console.error( + Logger.error( `waitFor rejecting after ${this.getTimeoutMs()}ms at ${new Date().toISOString()} with ${timeoutErrorMessage}` ); reject(new Error(timeoutErrorMessage)); @@ -71,6 +73,7 @@ export abstract class AbstractMessaging implements Messaging { const prom = this.waitFor(m => { return m.type == expectedTypeName && m.meta.requestUuid == message.meta.requestUuid; }, errorMessage); + Logger.debug('Sending to DesktopAgent: ', message); this.post(message); const out: X = await prom; if (out?.payload?.error) { diff --git a/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts b/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts new file mode 100644 index 000000000..0e81479a1 --- /dev/null +++ b/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts @@ -0,0 +1,89 @@ +/* eslint-disable @typescript-eslint/no-explicit-any */ + +//check if color is supported in (node) console; +let noColor = true; +//else only occurs in a browser and can't be tested in node +/* istanbul ignore if */ +if (typeof process !== 'undefined') { + const argv = process.argv || /* istanbul ignore next */ []; + const env = process.env || /* istanbul ignore next */ {}; + noColor = + (!!env.NO_COLOR || argv.includes('--no-color')) && + !( + !!env.FORCE_COLOR || + argv.includes('--color') || + process.platform === 'win32' /* istanbul ignore next */ || + ((process.stdout || {}).isTTY && env.TERM !== 'dumb') || + /* istanbul ignore next */ !!env.CI + ); +} + +type ColorFn = (aString: string) => string; + +export abstract class AbstractFDC3Logger { + private static enableDebug: boolean = false; + private static enableLog: boolean = true; + + /** This should be overridden by sub-classes to change the prefix applied + * to log messages. */ + static get prefix(): string { + return ''; + } + + public static enableDebugLogs(enable: boolean) { + this.enableDebug = enable; + } + + public static enableLogs(enable: boolean) { + this.enableLog = enable; + } + + protected static debugColor(value: string): string { + return noColor ? /* istanbul ignore next */ value : '\x1b[30m\x1b[2m' + value + '\x1b[22m\x1b[39m'; + } + protected static logColor(value: string): string { + return noColor ? /* istanbul ignore next */ value : '\x1b[32m\x1b[2m' + value + '\x1b[22m\x1b[39m'; + } + protected static warnColor(value: string): string { + return noColor ? /* istanbul ignore next */ value : '\x1b[33m' + value + '\x1b[39m'; + } + protected static errorColor(value: string): string { + return noColor ? /* istanbul ignore next */ value : '\x1b[31m' + value + '\x1b[39m'; + } + + public static debug(...params: any[]) { + if (this.enableDebug) { + console.debug(...this.prefixAndColorize(this.prefix, params, this.debugColor)); + } + } + + public static log(...params: any[]) { + if (this.enableLog) { + console.log(...this.prefixAndColorize(this.prefix, params, this.logColor)); + } + } + + public static warn(...params: any[]) { + console.warn(...this.prefixAndColorize(this.prefix, params, this.warnColor)); + } + + public static error(...params: any[]) { + console.error(...this.prefixAndColorize(this.prefix, params, this.errorColor)); + } + + protected static prefixAndColorize = (prefix: string, params: any[], colorFn: ColorFn): string[] => { + const prefixed = [prefix, ...params]; + return prefixed.map(value => { + if (typeof value === 'string') { + //just color strings + return colorFn(value); + } else if (value && value.stack && value.message) { + //probably an error + return colorFn(value.stack); + } else { + //something else... lets hope it stringifies + return colorFn(JSON.stringify(value, null, 2)); + } + }); + }; +} diff --git a/packages/fdc3-agent-proxy/src/util/Logger.ts b/packages/fdc3-agent-proxy/src/util/Logger.ts new file mode 100644 index 000000000..62aaeef06 --- /dev/null +++ b/packages/fdc3-agent-proxy/src/util/Logger.ts @@ -0,0 +1,19 @@ +import { AbstractFDC3Logger } from './AbstractFDC3Logger'; + +export class Logger extends AbstractFDC3Logger { + static override get prefix(): string { + return 'FDC3 DesktopAgentProxy: '; + } + + private static enableHeartbeatLog: boolean = true; + + public static enableHeartbeatLogs(enable: boolean) { + this.enableHeartbeatLog = enable; + } + + public static heartbeatLog(...params: any[]) { + if (this.enableHeartbeatLog) { + console.debug(...this.prefixAndColorize(this.prefix, params, this.debugColor)); + } + } +} diff --git a/packages/fdc3-agent-proxy/src/util.ts b/packages/fdc3-agent-proxy/src/util/throwIfUndefined.ts similarity index 84% rename from packages/fdc3-agent-proxy/src/util.ts rename to packages/fdc3-agent-proxy/src/util/throwIfUndefined.ts index a8dd30561..0b3434bb9 100644 --- a/packages/fdc3-agent-proxy/src/util.ts +++ b/packages/fdc3-agent-proxy/src/util/throwIfUndefined.ts @@ -1,5 +1,6 @@ import { AgentEventMessage, AgentResponseMessage } from '@finos/fdc3-schema/generated/api/BrowserTypes'; import { ChannelError, OpenError, ResolveError } from '@finos/fdc3-standard'; +import { Logger } from './Logger'; export type ErrorMessages = ChannelError | OpenError | ResolveError; @@ -14,7 +15,7 @@ export const throwIfUndefined = ( absentError: ErrorMessages ): void => { if (property === undefined) { - console.error(absentMessage, '\nDACP message that resulted in the undefined property: ', message); + Logger.error(absentMessage, '\nDACP message that resulted in the undefined property: ', message); throw new Error(absentError); } }; diff --git a/packages/fdc3-agent-proxy/test/features/utils.feature b/packages/fdc3-agent-proxy/test/features/utils.feature index 36ac80faa..6298470e3 100644 --- a/packages/fdc3-agent-proxy/test/features/utils.feature +++ b/packages/fdc3-agent-proxy/test/features/utils.feature @@ -3,4 +3,8 @@ Feature: Utility functions Scenario: throwIfUndefined is used to check properties When I call throwIfUndefined it throws if a specified property is not defined And I call throwIfUndefined it does NOT throw if a specified property IS defined + + Scenario: Logger utility + When All log functions are used with a message + When All log functions are used with an error \ No newline at end of file diff --git a/packages/fdc3-agent-proxy/test/step-definitions/channelSelector.steps.ts b/packages/fdc3-agent-proxy/test/step-definitions/channelSelector.steps.ts index 65fbb8592..5e8e8f19f 100644 --- a/packages/fdc3-agent-proxy/test/step-definitions/channelSelector.steps.ts +++ b/packages/fdc3-agent-proxy/test/step-definitions/channelSelector.steps.ts @@ -27,7 +27,7 @@ Given( const is = new DefaultIntentSupport(this.messaging, new SimpleIntentResolver(this)); const as = new DefaultAppSupport(this.messaging); - const da = new DesktopAgentProxy(hs, cs, is, as, [hs]); + const da = new DesktopAgentProxy(hs, cs, is, as, [hs], { debug: true, heartbeat: false }); await da.connect(); this.props[daField] = da; diff --git a/packages/fdc3-agent-proxy/test/step-definitions/generic.steps.ts b/packages/fdc3-agent-proxy/test/step-definitions/generic.steps.ts index 01eb1c13f..0e9dc0c79 100644 --- a/packages/fdc3-agent-proxy/test/step-definitions/generic.steps.ts +++ b/packages/fdc3-agent-proxy/test/step-definitions/generic.steps.ts @@ -22,7 +22,7 @@ Given('A Desktop Agent in {string}', async function (this: CustomWorld, field: s const is = new DefaultIntentSupport(this.messaging, new SimpleIntentResolver(this)); const as = new DefaultAppSupport(this.messaging); - const da = new DesktopAgentProxy(hs, cs, is, as, [hs]); + const da = new DesktopAgentProxy(hs, cs, is, as, [hs], { debug: false, heartbeat: false }); await da.connect(); this.props[field] = da; diff --git a/packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts b/packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts index 604c4613c..b5a9b2d36 100644 --- a/packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts +++ b/packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts @@ -1,9 +1,10 @@ import { When } from '@cucumber/cucumber'; import { CustomWorld } from '../world'; -import { throwIfUndefined } from '../../src/util'; +import { throwIfUndefined } from '../../src/util/throwIfUndefined'; import { AgentResponseMessage } from '@finos/fdc3-schema/generated/api/BrowserTypes'; import { OpenError } from '@finos/fdc3-standard'; import expect from 'expect'; +import { Logger } from '../../src/util/Logger'; When('I call throwIfUndefined it throws if a specified property is not defined', async function (this: CustomWorld) { let thrown: Error | null = null; @@ -61,3 +62,25 @@ When( expect(thrown).toBeNull(); } ); + +const TEST_ERROR = 'Test error - This is expected on the console'; + +When('All log functions are used with a message', async function (this: CustomWorld) { + Logger.enableDebugLogs(true); + Logger.enableHeartbeatLogs(true); + Logger.debug('Debug msg'); + Logger.heartbeatLog('Heartbeat debug msg'); + Logger.log('Log msg'); + Logger.warn('Warning msg'); + Logger.error('Error msg'); +}); + +When('All log functions are used with an error', async function (this: CustomWorld) { + Logger.enableDebugLogs(true); + Logger.enableHeartbeatLogs(true); + Logger.debug('debug-level error: ', new Error(TEST_ERROR)); + Logger.heartbeatLog('heartbeat debug-level error: ', new Error(TEST_ERROR)); + Logger.log('log-level error: ', new Error(TEST_ERROR)); + Logger.warn('warn-level error: ', new Error(TEST_ERROR)); + Logger.error('error-level error: ', new Error(TEST_ERROR)); +}); diff --git a/packages/fdc3-get-agent/src/messaging/message-port.ts b/packages/fdc3-get-agent/src/messaging/message-port.ts index 438ef2df0..01f76120b 100644 --- a/packages/fdc3-get-agent/src/messaging/message-port.ts +++ b/packages/fdc3-get-agent/src/messaging/message-port.ts @@ -20,7 +20,11 @@ import { Logger } from '../util/Logger'; */ export async function createDesktopAgentAPI( cd: ConnectionDetails, - appIdentifier: AppIdentifier + appIdentifier: AppIdentifier, + logging: { + heartbeat: boolean; + debug: boolean; + } ): Promise { Logger.debug('message-port: Creating Desktop Agent...'); @@ -53,7 +57,7 @@ export async function createDesktopAgentAPI( const cs = new DefaultChannelSupport(messaging, channelSelector); const is = new DefaultIntentSupport(messaging, intentResolver); const as = new DefaultAppSupport(messaging); - const da = new DesktopAgentProxy(hs, cs, is, as, [hs, intentResolver, channelSelector]); + const da = new DesktopAgentProxy(hs, cs, is, as, [hs, intentResolver, channelSelector], logging); Logger.debug('message-port: Connecting components ...'); diff --git a/packages/fdc3-get-agent/src/strategies/FailoverHandler.ts b/packages/fdc3-get-agent/src/strategies/FailoverHandler.ts index 0f4c29e25..736e97e72 100644 --- a/packages/fdc3-get-agent/src/strategies/FailoverHandler.ts +++ b/packages/fdc3-get-agent/src/strategies/FailoverHandler.ts @@ -6,6 +6,7 @@ import { HelloHandler } from './HelloHandler'; import { IdentityValidationHandler } from './IdentityValidationHandler'; import { Logger } from '../util/Logger'; import { ConnectionDetails } from '../messaging/MessagePortMessaging'; +import { DesktopAgentProxyLogSettings } from '@finos/fdc3-agent-proxy/src/DesktopAgentProxy'; /** TypeGuard for a Desktop Agent */ function isDesktopAgent(da: WindowProxy | DesktopAgent): da is DesktopAgent { @@ -90,8 +91,15 @@ export class FailoverHandler { appId: idDetails.payload.appId, instanceId: idDetails.payload.instanceId, }; + + //prep log settings to pass on to the proxy + const logging: DesktopAgentProxyLogSettings = { + debug: this.options.logging?.proxyDebug ?? false, + heartbeat: this.options.logging?.heartbeat ?? false, + }; + const desktopAgentSelection: DesktopAgentSelection = { - agent: await createDesktopAgentAPI(connectionDetails, appIdentifier), + agent: await createDesktopAgentAPI(connectionDetails, appIdentifier, logging), details: { agentType: connectionDetails.agentType, agentUrl: connectionDetails.agentUrl ?? undefined, diff --git a/packages/fdc3-get-agent/src/strategies/PostMessageLoader.ts b/packages/fdc3-get-agent/src/strategies/PostMessageLoader.ts index 0b4163a5d..1605de22e 100644 --- a/packages/fdc3-get-agent/src/strategies/PostMessageLoader.ts +++ b/packages/fdc3-get-agent/src/strategies/PostMessageLoader.ts @@ -5,6 +5,7 @@ import { DesktopAgentSelection, Loader } from './Loader'; import { HelloHandler } from './HelloHandler'; import { IdentityValidationHandler } from './IdentityValidationHandler'; import { Logger } from '../util/Logger'; +import { DesktopAgentProxyLogSettings } from '@finos/fdc3-agent-proxy/src/DesktopAgentProxy'; /** * Recursive search for all possible parent frames (windows) that we may @@ -41,8 +42,15 @@ function _recursePossibleTargets(startWindow: Window, w: Window, found: Window[] */ export class PostMessageLoader implements Loader { name = 'PostMessageLoader'; + private logging: DesktopAgentProxyLogSettings; + + constructor(options: GetAgentParams, previousUrl?: string) { + //prep log settings to pass on to the proxy + this.logging = { + debug: options.logging?.proxyDebug ?? false, + heartbeat: options.logging?.heartbeat ?? false, + }; - constructor(previousUrl?: string) { this.previousUrl = previousUrl ?? null; } @@ -128,7 +136,7 @@ export class PostMessageLoader implements Loader { instanceId: idDetails.payload.instanceId, }; - createDesktopAgentAPI(connectionDetails, appIdentifier).then(da => { + createDesktopAgentAPI(connectionDetails, appIdentifier, this.logging).then(da => { const desktopAgentSelection: DesktopAgentSelection = { agent: da, details: { diff --git a/packages/fdc3-get-agent/src/strategies/getAgent.ts b/packages/fdc3-get-agent/src/strategies/getAgent.ts index f89d99871..449846b28 100644 --- a/packages/fdc3-get-agent/src/strategies/getAgent.ts +++ b/packages/fdc3-get-agent/src/strategies/getAgent.ts @@ -51,20 +51,20 @@ function initAgentPromise(options: GetAgentParams): Promise { break; case WebDesktopAgentType.ProxyUrl: //agentUrl will only be used by PostMessageLoader if not falsey - strategies = [new PostMessageLoader(persistedData.agentUrl)]; + strategies = [new PostMessageLoader(options, persistedData.agentUrl)]; break; case WebDesktopAgentType.ProxyParent: - strategies = [new PostMessageLoader()]; + strategies = [new PostMessageLoader(options)]; break; case WebDesktopAgentType.Failover: strategies = []; break; default: Logger.warn('Unexpected agentType value in SessionStorage, ignoring. Stored data:', persistedData); - strategies = [new DesktopAgentPreloadLoader(), new PostMessageLoader()]; + strategies = [new DesktopAgentPreloadLoader(), new PostMessageLoader(options)]; } } else { - strategies = [new DesktopAgentPreloadLoader(), new PostMessageLoader()]; + strategies = [new DesktopAgentPreloadLoader(), new PostMessageLoader(options)]; } const promises = strategies.map(s => diff --git a/packages/fdc3-get-agent/src/util/Logger.ts b/packages/fdc3-get-agent/src/util/Logger.ts index a207a99b2..990b2a484 100644 --- a/packages/fdc3-get-agent/src/util/Logger.ts +++ b/packages/fdc3-get-agent/src/util/Logger.ts @@ -1,61 +1,7 @@ -/* eslint-disable @typescript-eslint/no-explicit-any */ -const GET_AGENT_LOG_PREFIX = 'FDC3 getAgent: '; +import { AbstractFDC3Logger } from '@finos/fdc3-agent-proxy'; -//check if color is supported in console; -let noColor = true; -//else only occurs in a browser and can't be tested in node -/* istanbul ignore if */ -if (typeof process !== 'undefined') { - const argv = process.argv || /* istanbul ignore next */ []; - const env = process.env || /* istanbul ignore next */ {}; - noColor = - (!!env.NO_COLOR || argv.includes('--no-color')) && - !( - !!env.FORCE_COLOR || - argv.includes('--color') || - process.platform === 'win32' /* istanbul ignore next */ || - ((process.stdout || {}).isTTY && env.TERM !== 'dumb') || - /* istanbul ignore next */ !!env.CI - ); -} - -type ColorFn = (aString: string) => string; - -const debugColor: ColorFn = value => (noColor ? value : '\x1b[30m\x1b[2m' + value + '\x1b[22m\x1b[39m'); -const logColor: ColorFn = value => (noColor ? value : '\x1b[32m\x1b[2m' + value + '\x1b[22m\x1b[39m'); -const warnColor: ColorFn = value => (noColor ? value : '\x1b[33m' + value + '\x1b[39m'); -const errorColor: ColorFn = value => (noColor ? value : '\x1b[31m' + value + '\x1b[39m'); - -const prefixAndColorize = (params: any[], colorFn: ColorFn): string[] => { - const prefixed = [GET_AGENT_LOG_PREFIX, ...params]; - return prefixed.map(value => { - if (typeof value === 'string') { - //just color strings - return colorFn(value); - } else if (value && value.stack && value.message) { - //probably an error - return colorFn(value.stack); - } else { - //something else... lets hope it stringifies - return colorFn(JSON.stringify(value, null, 2)); - } - }); -}; - -export class Logger { - static debug(...params: any[]) { - console.debug(...prefixAndColorize(params, debugColor)); - } - - static log(...params: any[]) { - console.log(...prefixAndColorize(params, logColor)); - } - - static warn(...params: any[]) { - console.warn(...prefixAndColorize(params, warnColor)); - } - - static error(...params: any[]) { - console.error(...prefixAndColorize(params, errorColor)); +export class Logger extends AbstractFDC3Logger { + static override get prefix(): string { + return 'FDC3 getAgent: '; } } diff --git a/packages/fdc3-get-agent/test/step-definitions/util.steps.ts b/packages/fdc3-get-agent/test/step-definitions/util.steps.ts index 1648e6a00..b330186af 100644 --- a/packages/fdc3-get-agent/test/step-definitions/util.steps.ts +++ b/packages/fdc3-get-agent/test/step-definitions/util.steps.ts @@ -1,24 +1,24 @@ -import { Given } from '@cucumber/cucumber'; +import { When } from '@cucumber/cucumber'; import { CustomWorld } from '../world'; import { Logger } from '../../src/util/Logger'; import { createUUID } from '../../src/util/Uuid'; const TEST_ERROR = 'Test error - This is expected on the console'; -Given('All log functions are used with a message', async function (this: CustomWorld) { +When('All log functions are used with a message', async function (this: CustomWorld) { Logger.debug('Debug msg'); Logger.log('Log msg'); Logger.warn('Warning msg'); Logger.error('Error msg'); }); -Given('All log functions are used with an error', async function (this: CustomWorld) { - Logger.debug(new Error(TEST_ERROR)); - Logger.log(new Error(TEST_ERROR)); - Logger.warn(new Error(TEST_ERROR)); - Logger.error(new Error(TEST_ERROR)); +When('All log functions are used with an error', async function (this: CustomWorld) { + Logger.debug('debug-level error: ', new Error(TEST_ERROR)); + Logger.log('log-level error: ', new Error(TEST_ERROR)); + Logger.warn('warn-level error: ', new Error(TEST_ERROR)); + Logger.error('error-level error: ', new Error(TEST_ERROR)); }); -Given('A uuid is generated', async function (this: CustomWorld) { +When('A uuid is generated', async function (this: CustomWorld) { return createUUID(); }); diff --git a/packages/fdc3-schema/generated/api/BrowserTypes.ts b/packages/fdc3-schema/generated/api/BrowserTypes.ts index 50ed6d23a..7e2af2655 100644 --- a/packages/fdc3-schema/generated/api/BrowserTypes.ts +++ b/packages/fdc3-schema/generated/api/BrowserTypes.ts @@ -1,15 +1,7 @@ // To parse this data: // -// import { Convert, WebConnectionProtocol1Hello, WebConnectionProtocol2LoadURL, WebConnectionProtocol3Handshake, WebConnectionProtocol4ValidateAppIdentity, WebConnectionProtocol5ValidateAppIdentityFailedResponse, WebConnectionProtocol5ValidateAppIdentitySuccessResponse, WebConnectionProtocol6Goodbye, WebConnectionProtocolMessage, AddContextListenerRequest, AddContextListenerResponse, AddEventListenerRequest, AddEventListenerResponse, AddIntentListenerRequest, AddIntentListenerResponse, AgentEventMessage, AgentResponseMessage, AppRequestMessage, BroadcastEvent, BroadcastRequest, BroadcastResponse, ChannelChangedEvent, ContextListenerUnsubscribeRequest, ContextListenerUnsubscribeResponse, CreatePrivateChannelRequest, CreatePrivateChannelResponse, EventListenerUnsubscribeRequest, EventListenerUnsubscribeResponse, Fdc3UserInterfaceChannelSelected, Fdc3UserInterfaceChannels, Fdc3UserInterfaceDrag, Fdc3UserInterfaceHandshake, Fdc3UserInterfaceHello, Fdc3UserInterfaceMessage, Fdc3UserInterfaceResolve, Fdc3UserInterfaceResolveAction, Fdc3UserInterfaceRestyle, FindInstancesRequest, FindInstancesResponse, FindIntentRequest, FindIntentResponse, FindIntentsByContextRequest, FindIntentsByContextResponse, GetAppMetadataRequest, GetAppMetadataResponse, GetCurrentChannelRequest, GetCurrentChannelResponse, GetCurrentContextRequest, GetCurrentContextResponse, GetInfoRequest, GetInfoResponse, GetOrCreateChannelRequest, GetOrCreateChannelResponse, GetUserChannelsRequest, GetUserChannelsResponse, HeartbeatAcknowledgementRequest, HeartbeatEvent, IntentEvent, IntentListenerUnsubscribeRequest, IntentListenerUnsubscribeResponse, IntentResultRequest, IntentResultResponse, JoinUserChannelRequest, JoinUserChannelResponse, LeaveCurrentChannelRequest, LeaveCurrentChannelResponse, OpenRequest, OpenResponse, PrivateChannelAddEventListenerRequest, PrivateChannelAddEventListenerResponse, PrivateChannelDisconnectRequest, PrivateChannelDisconnectResponse, PrivateChannelOnAddContextListenerEvent, PrivateChannelOnDisconnectEvent, PrivateChannelOnUnsubscribeEvent, PrivateChannelUnsubscribeEventListenerRequest, PrivateChannelUnsubscribeEventListenerResponse, RaiseIntentForContextRequest, RaiseIntentForContextResponse, RaiseIntentRequest, RaiseIntentResponse, RaiseIntentResultResponse } from "./file"; +// import { Convert, AddContextListenerRequest, AddContextListenerResponse, AddEventListenerRequest, AddEventListenerResponse, AddIntentListenerRequest, AddIntentListenerResponse, AgentEventMessage, AgentResponseMessage, AppRequestMessage, BroadcastEvent, BroadcastRequest, BroadcastResponse, ChannelChangedEvent, ContextListenerUnsubscribeRequest, ContextListenerUnsubscribeResponse, CreatePrivateChannelRequest, CreatePrivateChannelResponse, EventListenerUnsubscribeRequest, EventListenerUnsubscribeResponse, Fdc3UserInterfaceChannels, Fdc3UserInterfaceChannelSelected, Fdc3UserInterfaceDrag, Fdc3UserInterfaceHandshake, Fdc3UserInterfaceHello, Fdc3UserInterfaceMessage, Fdc3UserInterfaceResolve, Fdc3UserInterfaceResolveAction, Fdc3UserInterfaceRestyle, FindInstancesRequest, FindInstancesResponse, FindIntentRequest, FindIntentResponse, FindIntentsByContextRequest, FindIntentsByContextResponse, GetAppMetadataRequest, GetAppMetadataResponse, GetCurrentChannelRequest, GetCurrentChannelResponse, GetCurrentContextRequest, GetCurrentContextResponse, GetInfoRequest, GetInfoResponse, GetOrCreateChannelRequest, GetOrCreateChannelResponse, GetUserChannelsRequest, GetUserChannelsResponse, HeartbeatAcknowledgementRequest, HeartbeatEvent, IntentEvent, IntentListenerUnsubscribeRequest, IntentListenerUnsubscribeResponse, IntentResultRequest, IntentResultResponse, JoinUserChannelRequest, JoinUserChannelResponse, LeaveCurrentChannelRequest, LeaveCurrentChannelResponse, OpenRequest, OpenResponse, PrivateChannelAddEventListenerRequest, PrivateChannelAddEventListenerResponse, PrivateChannelDisconnectRequest, PrivateChannelDisconnectResponse, PrivateChannelOnAddContextListenerEvent, PrivateChannelOnDisconnectEvent, PrivateChannelOnUnsubscribeEvent, PrivateChannelUnsubscribeEventListenerRequest, PrivateChannelUnsubscribeEventListenerResponse, RaiseIntentForContextRequest, RaiseIntentForContextResponse, RaiseIntentRequest, RaiseIntentResponse, RaiseIntentResultResponse, WebConnectionProtocol1Hello, WebConnectionProtocol2LoadURL, WebConnectionProtocol3Handshake, WebConnectionProtocol4ValidateAppIdentity, WebConnectionProtocol5ValidateAppIdentityFailedResponse, WebConnectionProtocol5ValidateAppIdentitySuccessResponse, WebConnectionProtocol6Goodbye, WebConnectionProtocolMessage } from "./file"; // -// const webConnectionProtocol1Hello = Convert.toWebConnectionProtocol1Hello(json); -// const webConnectionProtocol2LoadURL = Convert.toWebConnectionProtocol2LoadURL(json); -// const webConnectionProtocol3Handshake = Convert.toWebConnectionProtocol3Handshake(json); -// const webConnectionProtocol4ValidateAppIdentity = Convert.toWebConnectionProtocol4ValidateAppIdentity(json); -// const webConnectionProtocol5ValidateAppIdentityFailedResponse = Convert.toWebConnectionProtocol5ValidateAppIdentityFailedResponse(json); -// const webConnectionProtocol5ValidateAppIdentitySuccessResponse = Convert.toWebConnectionProtocol5ValidateAppIdentitySuccessResponse(json); -// const webConnectionProtocol6Goodbye = Convert.toWebConnectionProtocol6Goodbye(json); -// const webConnectionProtocolMessage = Convert.toWebConnectionProtocolMessage(json); // const addContextListenerRequest = Convert.toAddContextListenerRequest(json); // const addContextListenerResponse = Convert.toAddContextListenerResponse(json); // const addEventListenerRequest = Convert.toAddEventListenerRequest(json); @@ -29,8 +21,8 @@ // const createPrivateChannelResponse = Convert.toCreatePrivateChannelResponse(json); // const eventListenerUnsubscribeRequest = Convert.toEventListenerUnsubscribeRequest(json); // const eventListenerUnsubscribeResponse = Convert.toEventListenerUnsubscribeResponse(json); -// const fdc3UserInterfaceChannelSelected = Convert.toFdc3UserInterfaceChannelSelected(json); // const fdc3UserInterfaceChannels = Convert.toFdc3UserInterfaceChannels(json); +// const fdc3UserInterfaceChannelSelected = Convert.toFdc3UserInterfaceChannelSelected(json); // const fdc3UserInterfaceDrag = Convert.toFdc3UserInterfaceDrag(json); // const fdc3UserInterfaceHandshake = Convert.toFdc3UserInterfaceHandshake(json); // const fdc3UserInterfaceHello = Convert.toFdc3UserInterfaceHello(json); @@ -83,552 +75,960 @@ // const raiseIntentRequest = Convert.toRaiseIntentRequest(json); // const raiseIntentResponse = Convert.toRaiseIntentResponse(json); // const raiseIntentResultResponse = Convert.toRaiseIntentResultResponse(json); +// const webConnectionProtocol1Hello = Convert.toWebConnectionProtocol1Hello(json); +// const webConnectionProtocol2LoadURL = Convert.toWebConnectionProtocol2LoadURL(json); +// const webConnectionProtocol3Handshake = Convert.toWebConnectionProtocol3Handshake(json); +// const webConnectionProtocol4ValidateAppIdentity = Convert.toWebConnectionProtocol4ValidateAppIdentity(json); +// const webConnectionProtocol5ValidateAppIdentityFailedResponse = Convert.toWebConnectionProtocol5ValidateAppIdentityFailedResponse(json); +// const webConnectionProtocol5ValidateAppIdentitySuccessResponse = Convert.toWebConnectionProtocol5ValidateAppIdentitySuccessResponse(json); +// const webConnectionProtocol6Goodbye = Convert.toWebConnectionProtocol6Goodbye(json); +// const webConnectionProtocolMessage = Convert.toWebConnectionProtocolMessage(json); // // These functions will throw an error if the JSON doesn't // match the expected interface, even if the JSON is valid. /** - * Hello message sent by an application to a parent window or frame when attempting to - * establish connectivity to a Desktop Agent. + * A request to add a context listener to a specified Channel OR to the current user + * channel. Where the listener is added to the current user channel (channelId == null), and + * this app has already been added to a user channel, client code should make a subsequent + * request to get the current context of that channel for this listener and then call its + * handler with it. * - * A message used during the connection flow for an application to a Desktop Agent in a - * browser window. Used for messages sent in either direction. + * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface WebConnectionProtocol1Hello { +export interface AddContextListenerRequest { /** - * Metadata for a Web Connection Protocol message. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - meta: WebConnectionProtocol1HelloMeta; + meta: AddContextListenerRequestMeta; /** - * The message payload, containing data pertaining to this connection step. + * The message payload typically contains the arguments to FDC3 API functions. */ - payload: WebConnectionProtocol1HelloPayload; + payload: AddContextListenerRequestPayload; /** - * Identifies the type of the connection step message. + * 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. */ - type: 'WCP1Hello'; + type: 'addContextListenerRequest'; } /** - * Metadata for a Web Connection Protocol message. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ -export interface WebConnectionProtocol1HelloMeta { - connectionAttemptUuid: string; +export interface AddContextListenerRequestMeta { + requestUuid: string; + /** + * Field that represents the source application that a request or response was received + * from. Please note that this may be set by an app or Desktop Agent proxy for debugging + * purposes but a Desktop Agent should make its own determination of the source of a message + * to avoid spoofing. + */ + source?: AppIdentifier; timestamp: Date; } /** - * The message payload, containing data pertaining to this connection step. + * Field that represents the source application that a request or response was received + * from. Please note that this may be set by an app or Desktop Agent proxy for debugging + * purposes but a Desktop Agent should make its own determination of the source of a message + * to avoid spoofing. + * + * Identifies an application, or instance of an application, and is used to target FDC3 API + * calls, such as `fdc3.open` or `fdc3.raiseIntent` at specific applications or application + * instances. + * + * Will always include at least an `appId` field, which uniquely identifies a specific app. + * + * If the `instanceId` field is set then the `AppMetadata` object represents a specific + * instance of the application that may be addressed using that Id. + * + * Field that represents the source application that the request being responded to was + * received from, for debugging purposes. + * + * Details of the application instance that broadcast the context. + * + * The App resolution option chosen. + * + * Details of the application instance that raised the intent. + * + * Identifier for the app instance that was selected (or started) to resolve the intent. + * `source.instanceId` MUST be set, indicating the specific app instance that + * received the intent. */ -export interface WebConnectionProtocol1HelloPayload { +export interface AppIdentifier { /** - * The current URL of the page attempting to connect. This may differ from the identityUrl, - * but the origins MUST match. + * The unique application identifier located within a specific application directory + * instance. An example of an appId might be 'app@sub.root'. */ - actualUrl: string; + appId: string; /** - * A flag that may be used to indicate that a channel selector user interface is or is not - * required. Set to `false` if the app includes its own interface for selecting channels or - * does not work with user channels. + * The Desktop Agent that the app is available on. Used in Desktop Agent Bridging to + * identify the Desktop Agent to target. */ - channelSelector?: boolean; + desktopAgent?: string; /** - * The version of FDC3 API that the app supports. + * An optional instance identifier, indicating that this object represents a specific + * instance of the application described. */ - fdc3Version: string; + instanceId?: string; + [property: string]: any; +} + +/** + * The message payload typically contains the arguments to FDC3 API functions. + */ +export interface AddContextListenerRequestPayload { /** - * URL to use for the identity of the application. Desktop Agents MUST validate that the - * origin of the message matches the URL, but MAY implement custom comparison logic. + * The id of the channel to add the listener to or `null` indicating that it should listen + * to the current user channel (at the time of broadcast). */ - identityUrl: string; + channelId: null | string; /** - * A flag that may be used to indicate that an intent resolver is or is not required. Set to - * `false` if no intents, or only targeted intents, are raised. + * The type of context to listen for OR `null` indicating that it should listen to all + * context types. */ - intentResolver?: boolean; - [property: string]: any; + contextType: null | string; } /** - * Identifies the type of the connection step message. + * 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. */ /** - * Response from a Desktop Agent to an application requesting access to it indicating that - * it should load a specified URL into a hidden iframe in order to establish connectivity to - * a Desktop Agent. + * A response to a addContextListener request. Where the listener was added to the current + * user channel (channelId == null), and this app has already been added to a user channel, + * client code should make a subsequent request to get the current context of that channel + * for this listener and then call its handler with it. * - * A message used during the connection flow for an application to a Desktop Agent in a - * browser window. Used for messages sent in either direction. + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. */ -export interface WebConnectionProtocol2LoadURL { +export interface AddContextListenerResponse { /** - * Metadata for a Web Connection Protocol message. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - meta: WebConnectionProtocol1HelloMeta; + meta: AddContextListenerResponseMeta; /** - * The message payload, containing data pertaining to this connection step. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ - payload: WebConnectionProtocol2LoadURLPayload; + payload: AddContextListenerResponsePayload; /** - * Identifies the type of the connection step message. + * 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. */ - type: 'WCP2LoadUrl'; + type: 'addContextListenerResponse'; } /** - * The message payload, containing data pertaining to this connection step. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ -export interface WebConnectionProtocol2LoadURLPayload { +export interface AddContextListenerResponseMeta { + requestUuid: string; + responseUuid: string; /** - * A URL which can be used to establish communication with the Desktop Agent, via loading - * the URL into an iframe and restarting the Web Connection protocol with the iframe as the - * target. + * Field that represents the source application that the request being responded to was + * received from, for debugging purposes. */ - iframeUrl: string; - [property: string]: any; + source?: AppIdentifier; + timestamp: Date; } /** - * Identifies the type of the connection step message. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ +export interface AddContextListenerResponsePayload { + error?: PurpleError; + listenerUUID?: string; +} /** - * Handshake message sent by the Desktop Agent to the app (with a MessagePort appended) that - * should be used for subsequent communication steps. + * Constants representing the errors that can be encountered when calling the `open` method + * on the DesktopAgent object (`fdc3`). * - * A message used during the connection flow for an application to a Desktop Agent in a - * browser window. Used for messages sent in either direction. + * Constants representing the errors that can be encountered when calling the `findIntent`, + * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the + * DesktopAgent (`fdc3`). */ -export interface WebConnectionProtocol3Handshake { +export type PurpleError = 'AccessDenied' | 'CreationFailed' | 'MalformedContext' | 'NoChannelFound'; + +/** + * 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. + */ + +/** + * A request to add an event listener for a specified event type to the Desktop Agent. + * + * A request message from an FDC3-enabled app to a Desktop Agent. + */ +export interface AddEventListenerRequest { /** - * Metadata for a Web Connection Protocol message. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - meta: WebConnectionProtocol1HelloMeta; + meta: AddContextListenerRequestMeta; /** - * The message payload, containing data pertaining to this connection step. + * The message payload typically contains the arguments to FDC3 API functions. */ - payload: WebConnectionProtocol3HandshakePayload; + payload: AddEventListenerRequestPayload; /** - * Identifies the type of the connection step message. + * 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. */ - type: 'WCP3Handshake'; + type: 'addEventListenerRequest'; } /** - * The message payload, containing data pertaining to this connection step. + * The message payload typically contains the arguments to FDC3 API functions. */ -export interface WebConnectionProtocol3HandshakePayload { - /** - * Indicates whether a channel selector user interface is required and the URL to use to do - * so. Set to `true` to use the default or `false` to disable the channel selector (as the - * Desktop Agent will handle it another way). - */ - channelSelectorUrl: boolean | string; - /** - * The version of FDC3 API that the Desktop Agent will provide support for. - */ - fdc3Version: string; +export interface AddEventListenerRequestPayload { /** - * Indicates whether an intent resolver user interface is required and the URL to use to do - * so. Set to `true` to use the default or `false` to disable the intent resolver (as the - * Desktop Agent will handle it another way). + * The type of the event to be listened to or `null` to listen to all event types. */ - intentResolverUrl: boolean | string; + type: 'USER_CHANNEL_CHANGED' | null; } /** - * Identifies the type of the connection step message. + * The type of a (non-context and non-intent) event that may be received via the FDC3 API's + * addEventListener function. */ /** - * Identity Validation request from an app attempting to connect to a Desktop Agent. + * 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. + */ + +/** + * A response to an addEventListener request. * - * A message used during the connection flow for an application to a Desktop Agent in a - * browser window. Used for messages sent in either direction. + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. */ -export interface WebConnectionProtocol4ValidateAppIdentity { +export interface AddEventListenerResponse { /** - * Metadata for a Web Connection Protocol message. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - meta: WebConnectionProtocol1HelloMeta; + meta: AddContextListenerResponseMeta; /** - * The message payload, containing data pertaining to this connection step. - */ - payload: WebConnectionProtocol4ValidateAppIdentityPayload; + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. + */ + payload: AddEventListenerResponsePayload; /** - * Identifies the type of the connection step message. + * 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. */ - type: 'WCP4ValidateAppIdentity'; + type: 'addEventListenerResponse'; } /** - * The message payload, containing data pertaining to this connection step. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface WebConnectionProtocol4ValidateAppIdentityPayload { - /** - * The current URL of the page attempting to connect. This may differ from the identityUrl, - * but the origins MUST match. - */ - actualUrl: string; - /** - * URL to use for the identity of the application. Desktop Agents MUST validate that the - * origin of the message matches the URL, but MAY implement custom comparison logic. - */ - identityUrl: string; - /** - * If an application has previously connected to the Desktop Agent, it may specify its prior - * instance id and associated instance UUID to request the same same instance Id be assigned. - */ - instanceId?: string; - /** - * Instance UUID associated with the requested instanceId. - */ - instanceUuid?: string; +export interface AddEventListenerResponsePayload { + error?: ResponsePayloadError; + listenerUUID?: string; } /** - * Identifies the type of the connection step message. + * 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`). + */ +export type ResponsePayloadError = + | 'AccessDenied' + | 'CreationFailed' + | 'MalformedContext' + | 'NoChannelFound' + | 'AppNotFound' + | 'AppTimeout' + | 'DesktopAgentNotFound' + | 'ErrorOnLaunch' + | 'ResolverUnavailable' + | 'IntentDeliveryFailed' + | 'NoAppsFound' + | 'ResolverTimeout' + | 'TargetAppUnavailable' + | 'TargetInstanceUnavailable' + | 'UserCancelledResolution' + | 'IntentHandlerRejected' + | 'NoResultReturned' + | 'AgentDisconnected' + | 'NotConnectedToBridge' + | 'ResponseToBridgeTimedOut' + | 'MalformedMessage'; + +/** + * 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. */ /** - * Message sent by the Desktop Agent to an app if their identity validation fails. + * A request to add an Intent listener for a specified intent type. * - * A message used during the connection flow for an application to a Desktop Agent in a - * browser window. Used for messages sent in either direction. + * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface WebConnectionProtocol5ValidateAppIdentityFailedResponse { +export interface AddIntentListenerRequest { /** - * Metadata for a Web Connection Protocol message. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - meta: WebConnectionProtocol1HelloMeta; + meta: AddContextListenerRequestMeta; /** - * The message payload, containing data pertaining to this connection step. + * The message payload typically contains the arguments to FDC3 API functions. */ - payload: WebConnectionProtocol5ValidateAppIdentityFailedResponsePayload; + payload: AddIntentListenerRequestPayload; /** - * Identifies the type of the connection step message. + * 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. */ - type: 'WCP5ValidateAppIdentityFailedResponse'; + type: 'addIntentListenerRequest'; } /** - * The message payload, containing data pertaining to this connection step. + * The message payload typically contains the arguments to FDC3 API functions. */ -export interface WebConnectionProtocol5ValidateAppIdentityFailedResponsePayload { - message?: string; +export interface AddIntentListenerRequestPayload { + /** + * The name of the intent to listen for. + */ + intent: string; } /** - * Identifies the type of the connection step message. + * 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. */ /** - * Message sent by the Desktop Agent to an app after successful identity validation. + * A response to a addIntentListener request. * - * A message used during the connection flow for an application to a Desktop Agent in a - * browser window. Used for messages sent in either direction. + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. */ -export interface WebConnectionProtocol5ValidateAppIdentitySuccessResponse { +export interface AddIntentListenerResponse { /** - * Metadata for a Web Connection Protocol message. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - meta: WebConnectionProtocol1HelloMeta; + meta: AddContextListenerResponseMeta; /** - * The message payload, containing data pertaining to this connection step. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ - payload: WebConnectionProtocol5ValidateAppIdentitySuccessResponsePayload; + payload: PayloadObject; /** - * Identifies the type of the connection step message. + * 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. */ - type: 'WCP5ValidateAppIdentityResponse'; + type: 'addIntentListenerResponse'; } /** - * The message payload, containing data pertaining to this connection step. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface WebConnectionProtocol5ValidateAppIdentitySuccessResponsePayload { - /** - * The appId that the app's identity was validated against. - */ - appId: string; - /** - * Implementation metadata for the Desktop Agent, which includes an appMetadata element - * containing a copy of the app's own metadata. - */ - implementationMetadata: ImplementationMetadata; - /** - * The instance Id granted to the application by the Desktop Agent. - */ - instanceId: string; - /** - * Instance UUID associated with the instanceId granted, which may be used to retrieve the - * same instanceId if the app is reloaded or navigates. - */ - instanceUuid: string; +export interface PayloadObject { + error?: FluffyError; + listenerUUID?: string; + [property: string]: any; } /** - * Implementation metadata for the Desktop Agent, which includes an appMetadata element - * containing a copy of the app's own metadata. - * - * Includes Metadata for the current application. + * Constants representing the errors that can be encountered when calling the `open` method + * on the DesktopAgent object (`fdc3`). * - * Metadata relating to the FDC3 Desktop Agent implementation and its provider. + * Constants representing the errors that can be encountered when calling the `findIntent`, + * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the + * DesktopAgent (`fdc3`). */ -export interface ImplementationMetadata { - /** - * The calling application instance's own metadata, according to the Desktop Agent (MUST - * include at least the `appId` and `instanceId`). - */ - appMetadata: AppMetadata; - /** - * The version number of the FDC3 specification that the implementation provides. - * The string must be a numeric semver version, e.g. 1.2 or 1.2.1. - */ - fdc3Version: string; - /** - * Metadata indicating whether the Desktop Agent implements optional features of - * the Desktop Agent API. - */ - optionalFeatures: OptionalFeatures; - /** - * The name of the provider of the Desktop Agent implementation (e.g. Finsemble, Glue42, - * OpenFin etc.). - */ - provider: string; - /** - * The version of the provider of the Desktop Agent implementation (e.g. 5.3.0). - */ - providerVersion?: string; +export type FluffyError = + | 'MalformedContext' + | 'DesktopAgentNotFound' + | 'ResolverUnavailable' + | 'IntentDeliveryFailed' + | 'NoAppsFound' + | 'ResolverTimeout' + | 'TargetAppUnavailable' + | 'TargetInstanceUnavailable' + | 'UserCancelledResolution'; + +/** + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. + */ +export interface AgentEventMessageMeta { + eventUuid: string; + timestamp: Date; } /** - * The calling application instance's own metadata, according to the Desktop Agent (MUST - * include at least the `appId` and `instanceId`). - * - * Extends an `AppIdentifier`, describing an application or instance of an application, with - * additional descriptive metadata that is usually provided by an FDC3 App Directory that - * the Desktop Agent connects to. - * - * The additional information from an app directory can aid in rendering UI elements, such - * as a launcher menu or resolver UI. This includes a title, description, tooltip and icon - * and screenshot URLs. - * - * Note that as `AppMetadata` instances are also `AppIdentifiers` they may be passed to the - * `app` argument of `fdc3.open`, `fdc3.raiseIntent` etc. + * 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. */ -export interface AppMetadata { - /** - * The unique application identifier located within a specific application directory - * instance. An example of an appId might be 'app@sub.root'. - */ - appId: string; - /** - * A longer, multi-paragraph description for the application that could include markup. - */ - description?: string; - /** - * The Desktop Agent that the app is available on. Used in Desktop Agent Bridging to - * identify the Desktop Agent to target. - */ - desktopAgent?: string; +export type EventMessageType = + | 'addEventListenerEvent' + | 'broadcastEvent' + | 'channelChangedEvent' + | 'heartbeatEvent' + | 'intentEvent' + | 'privateChannelOnAddContextListenerEvent' + | 'privateChannelOnDisconnectEvent' + | 'privateChannelOnUnsubscribeEvent'; + +/** + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + */ +export interface AgentResponseMessageMeta { + requestUuid: string; + responseUuid: string; /** - * A list of icon URLs for the application that can be used to render UI elements. + * Field that represents the source application that the request being responded to was + * received from, for debugging purposes. */ - icons?: Icon[]; - /** - * An optional instance identifier, indicating that this object represents a specific - * instance of the application described. + source?: AppIdentifier; + timestamp: Date; +} + +/** + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. + */ +export interface AgentResponseMessageResponsePayload { + error?: ResponsePayloadError; + [property: string]: any; +} + +/** + * 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. + */ +export type ResponseMessageType = + | 'addContextListenerResponse' + | 'addEventListenerResponse' + | 'addIntentListenerResponse' + | 'broadcastResponse' + | 'contextListenerUnsubscribeResponse' + | 'createPrivateChannelResponse' + | 'eventListenerUnsubscribeResponse' + | 'findInstancesResponse' + | 'findIntentResponse' + | 'findIntentsByContextResponse' + | 'getAppMetadataResponse' + | 'getCurrentChannelResponse' + | 'getCurrentContextResponse' + | 'getInfoResponse' + | 'getOrCreateChannelResponse' + | 'getUserChannelsResponse' + | 'intentListenerUnsubscribeResponse' + | 'intentResultResponse' + | 'joinUserChannelResponse' + | 'leaveCurrentChannelResponse' + | 'openResponse' + | 'privateChannelAddEventListenerResponse' + | 'privateChannelDisconnectResponse' + | 'privateChannelUnsubscribeEventListenerResponse' + | 'raiseIntentForContextResponse' + | 'raiseIntentResponse' + | 'raiseIntentResultResponse'; + +/** + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + */ +export interface AppRequestMessageMeta { + requestUuid: string; + /** + * Field that represents the source application that a request or response was received + * from. Please note that this may be set by an app or Desktop Agent proxy for debugging + * purposes but a Desktop Agent should make its own determination of the source of a message + * to avoid spoofing. */ - instanceId?: string; + source?: AppIdentifier; + timestamp: Date; +} + +/** + * 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. + */ +export type RequestMessageType = + | 'addContextListenerRequest' + | 'addEventListenerRequest' + | 'addIntentListenerRequest' + | 'broadcastRequest' + | 'contextListenerUnsubscribeRequest' + | 'createPrivateChannelRequest' + | 'eventListenerUnsubscribeRequest' + | 'findInstancesRequest' + | 'findIntentRequest' + | 'findIntentsByContextRequest' + | 'getAppMetadataRequest' + | 'getCurrentChannelRequest' + | 'getCurrentContextRequest' + | 'getInfoRequest' + | 'getOrCreateChannelRequest' + | 'getUserChannelsRequest' + | 'heartbeatAcknowledgementRequest' + | 'intentListenerUnsubscribeRequest' + | 'intentResultRequest' + | 'joinUserChannelRequest' + | 'leaveCurrentChannelRequest' + | 'openRequest' + | 'privateChannelAddEventListenerRequest' + | 'privateChannelDisconnectRequest' + | 'privateChannelUnsubscribeEventListenerRequest' + | 'raiseIntentForContextRequest' + | 'raiseIntentRequest'; + +/** + * An event message from the Desktop Agent to an app indicating that context has been + * broadcast on a channel it is listening to, or specifically to this app instance if it was + * launched via `fdc3.open` and context was passed. + * + * A message from a Desktop Agent to an FDC3-enabled app representing an event. + */ +export interface BroadcastEvent { /** - * An optional set of, implementation specific, metadata fields that can be used to - * disambiguate instances, such as a window title or screen position. Must only be set if - * `instanceId` is set. + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. */ - instanceMetadata?: { [key: string]: any }; + meta: BroadcastEventMeta; /** - * The 'friendly' app name. - * This field was used with the `open` and `raiseIntent` calls in FDC3 <2.0, which now - * require an `AppIdentifier` wth `appId` set. - * Note that for display purposes the `title` field should be used, if set, in preference to - * this field. + * The message payload contains details of the event that the app is being notified about. + */ + payload: BroadcastEventPayload; + /** + * 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. + */ + type: 'broadcastEvent'; +} + +/** + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. + */ +export interface BroadcastEventMeta { + eventUuid: string; + timestamp: Date; +} + +/** + * The message payload contains details of the event that the app is being notified about. + */ +export interface BroadcastEventPayload { + /** + * The Id of the channel that the broadcast was sent on. May be `null` if the context is + * being broadcast due to a call `fdc3.open` that passed context. + */ + channelId: null | string; + /** + * The context object that was broadcast. + */ + context: Context; + /** + * Details of the application instance that broadcast the context. + */ + originatingApp?: AppIdentifier; +} + +/** + * The context object that was broadcast. + * + * The context object that is to be broadcast. + * + * The context object passed with the raised intent. + * + * If a Context object is passed in, this object will be provided to the opened application + * via a contextListener. The Context argument is functionally equivalent to opening the + * target app with no context and broadcasting the context directly to it. + * + * The `fdc3.context` type defines the basic contract or "shape" for all data exchanged by + * FDC3 operations. As such, it is not really meant to be used on its own, but is imported + * by more specific type definitions (standardized or custom) to provide the structure and + * properties shared by all FDC3 context data types. + * + * The key element of FDC3 context types is their mandatory `type` property, which is used + * to identify what type of data the object represents, and what shape it has. + * + * The FDC3 context type, and all derived types, define the minimum set of fields a context + * data object of a particular type can be expected to have, but this can always be extended + * with custom fields as appropriate. + */ +export interface Context { + /** + * Context data objects may include a set of equivalent key-value pairs that can be used to + * help applications identify and look up the context type they receive in their own domain. + * The idea behind this design is that applications can provide as many equivalent + * identifiers to a target application as possible, e.g. an instrument may be represented by + * an ISIN, CUSIP or Bloomberg identifier. + * + * Identifiers do not make sense for all types of data, so the `id` property is therefore + * optional, but some derived types may choose to require at least one identifier. + * Identifier values SHOULD always be of type string. + */ + id?: { [key: string]: any }; + /** + * Context data objects may include a name property that can be used for more information, + * or display purposes. Some derived types may require the name object as mandatory, + * depending on use case. */ name?: string; /** - * The type of output returned for any intent specified during resolution. May express a - * particular context type (e.g. "fdc3.instrument"), channel (e.g. "channel") or a channel - * that will receive a specified type (e.g. "channel"). + * The type property is the only _required_ part of the FDC3 context data schema. The FDC3 + * [API](https://fdc3.finos.org/docs/api/spec) relies on the `type` property being present + * to route shared context data appropriately. + * + * FDC3 [Intents](https://fdc3.finos.org/docs/intents/spec) also register the context data + * types they support in an FDC3 [App + * Directory](https://fdc3.finos.org/docs/app-directory/overview), used for intent discovery + * and routing. + * + * Standardized FDC3 context types have well-known `type` properties prefixed with the + * `fdc3` namespace, e.g. `fdc3.instrument`. For non-standard types, e.g. those defined and + * used by a particular organization, the convention is to prefix them with an + * organization-specific namespace, e.g. `blackrock.fund`. + * + * See the [Context Data Specification](https://fdc3.finos.org/docs/context/spec) for more + * information about context data types. */ - resultType?: null | string; + type: string; + [property: string]: any; +} + +/** + * 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. + */ + +/** + * A request to broadcast context on a channel. + * + * A request message from an FDC3-enabled app to a Desktop Agent. + */ +export interface BroadcastRequest { /** - * Images representing the app in common usage scenarios that can be used to render UI - * elements. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - screenshots?: Image[]; + meta: AddContextListenerRequestMeta; /** - * A more user-friendly application title that can be used to render UI elements. + * The message payload typically contains the arguments to FDC3 API functions. */ - title?: string; + payload: BroadcastRequestPayload; /** - * A tooltip for the application that can be used to render UI elements. + * 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. */ - tooltip?: string; + type: 'broadcastRequest'; +} + +/** + * The message payload typically contains the arguments to FDC3 API functions. + */ +export interface BroadcastRequestPayload { /** - * The Version of the application. + * The Id of the Channel that the broadcast was sent on. */ - version?: string; + channelId: string; + /** + * The context object that is to be broadcast. + */ + context: Context; } /** - * Describes an Icon image that may be used to represent the application. + * 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. */ -export interface Icon { + +/** + * A response to a request to broadcast context on a channel. + * + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. + */ +export interface BroadcastResponse { /** - * The icon dimension, formatted as `x`. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - size?: string; + meta: AddContextListenerResponseMeta; /** - * The icon url. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ - src: string; + payload: BroadcastResponseResponsePayload; /** - * Icon media type. If not present the Desktop Agent may use the src file extension. + * 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. */ - type?: string; + type: 'broadcastResponse'; } /** - * Describes an image file, typically a screenshot, that often represents the application in - * a common usage scenario. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface Image { +export interface BroadcastResponseResponsePayload { + error?: ResponsePayloadError; + [property: string]: any; +} + +/** + * 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. + */ + +/** + * An event message from the Desktop Agent to an app indicating that its current user + * channel has changed. + * + * A message from a Desktop Agent to an FDC3-enabled app representing an event. + */ +export interface ChannelChangedEvent { /** - * Caption for the image. + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. */ - label?: string; + meta: BroadcastEventMeta; /** - * The image dimension, formatted as `x`. + * The message payload contains details of the event that the app is being notified about. */ - size?: string; + payload: ChannelChangedEventPayload; /** - * The image url. + * 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. */ - src: string; + type: 'channelChangedEvent'; +} + +/** + * The message payload contains details of the event that the app is being notified about. + */ +export interface ChannelChangedEventPayload { /** - * Image media type. If not present the Desktop Agent may use the src file extension. + * The Id of the channel that the app was added to or `null` if it was removed from a + * channel. */ - type?: string; + newChannelId: null | string; } /** - * Metadata indicating whether the Desktop Agent implements optional features of - * the Desktop Agent API. + * 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. */ -export interface OptionalFeatures { + +/** + * A request to unsubscribe a context listener. + * + * A request message from an FDC3-enabled app to a Desktop Agent. + */ +export interface ContextListenerUnsubscribeRequest { /** - * Used to indicate whether the experimental Desktop Agent Bridging - * feature is implemented by the Desktop Agent. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - DesktopAgentBridging: boolean; + meta: AddContextListenerRequestMeta; /** - * Used to indicate whether the exposure of 'originating app metadata' for - * context and intent messages is supported by the Desktop Agent. + * The message payload typically contains the arguments to FDC3 API functions. */ - OriginatingAppMetadata: boolean; + payload: ContextListenerUnsubscribeRequestPayload; /** - * Used to indicate whether the optional `fdc3.joinUserChannel`, - * `fdc3.getCurrentChannel` and `fdc3.leaveCurrentChannel` are implemented by - * the Desktop Agent. + * 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. */ - UserChannelMembershipAPIs: boolean; + type: 'contextListenerUnsubscribeRequest'; } /** - * Identifies the type of the connection step message. + * The message payload typically contains the arguments to FDC3 API functions. */ +export interface ContextListenerUnsubscribeRequestPayload { + listenerUUID: string; +} /** - * Goodbye message to be sent to the Desktop Agent when disconnecting (e.g. when closing the - * window or navigating). Desktop Agents should close the MessagePort after receiving this - * message, but retain instance details in case the application reconnects (e.g. after a - * navigation event). + * 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. + */ + +/** + * A response to a contextListenerUnsubscribe request. * - * A message used during the connection flow for an application to a Desktop Agent in a - * browser window. Used for messages sent in either direction. + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. */ -export interface WebConnectionProtocol6Goodbye { +export interface ContextListenerUnsubscribeResponse { /** - * Metadata for a Web Connection Protocol message. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - meta: WebConnectionProtocol6GoodbyeMeta; + meta: AddContextListenerResponseMeta; + /** + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. + */ + payload: BroadcastResponseResponsePayload; + /** + * 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. + */ + type: 'contextListenerUnsubscribeResponse'; +} + +/** + * 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. + */ + +/** + * Request to return a Channel with an auto-generated identity that is intended for private + * communication between applications. + * + * A request message from an FDC3-enabled app to a Desktop Agent. + */ +export interface CreatePrivateChannelRequest { + /** + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + */ + meta: AddContextListenerRequestMeta; + /** + * The message payload typically contains the arguments to FDC3 API functions. + */ + payload: CreatePrivateChannelRequestPayload; + /** + * 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. + */ + type: 'createPrivateChannelRequest'; +} + +/** + * The message payload typically contains the arguments to FDC3 API functions. + */ +export interface CreatePrivateChannelRequestPayload {} + +/** + * 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. + */ + +/** + * A response to a createPrivateChannel request. + * + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. + */ +export interface CreatePrivateChannelResponse { + /** + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + */ + meta: AddContextListenerResponseMeta; + /** + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. + */ + payload: CreatePrivateChannelResponsePayload; /** - * Identifies the type of the connection step message. + * 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. */ - type: 'WCP6Goodbye'; + type: 'createPrivateChannelResponse'; } /** - * Metadata for a Web Connection Protocol message. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface WebConnectionProtocol6GoodbyeMeta { - timestamp: Date; +export interface CreatePrivateChannelResponsePayload { + error?: PurpleError; + privateChannel?: Channel; } /** - * Identifies the type of the connection step message. + * Represents a context channel that applications can use to send and receive + * context data. + * + * Please note that There are differences in behavior when you interact with a + * User channel via the `DesktopAgent` interface and the `Channel` interface. + * Specifically, when 'joining' a User channel or adding a context listener + * when already joined to a channel via the `DesktopAgent` interface, existing + * context (matching the type of the context listener) on the channel is + * received by the context listener immediately. Whereas, when a context + * listener is added via the Channel interface, context is not received + * automatically, but may be retrieved manually via the `getCurrentContext()` + * function. */ +export interface Channel { + /** + * Channels may be visualized and selectable by users. DisplayMetadata may be used to + * provide hints on how to see them. + * For App channels, displayMetadata would typically not be present. + */ + displayMetadata?: DisplayMetadata; + /** + * Constant that uniquely identifies this channel. + */ + id: string; + /** + * Uniquely defines each channel type. + * Can be "user", "app" or "private". + */ + type: Type; +} /** - * A message used during the connection flow for an application to a Desktop Agent in a - * browser window. Used for messages sent in either direction. + * Channels may be visualized and selectable by users. DisplayMetadata may be used to + * provide hints on how to see them. + * For App channels, displayMetadata would typically not be present. + * + * A system channel will be global enough to have a presence across many apps. This gives us + * some hints + * to render them in a standard way. It is assumed it may have other properties too, but if + * it has these, + * this is their meaning. */ -export interface WebConnectionProtocolMessage { +export interface DisplayMetadata { /** - * Metadata for a Web Connection Protocol message. + * The color that should be associated within this channel when displaying this channel in a + * UI, e.g: `0xFF0000`. */ - meta: ConnectionStepMetadata; + color?: string; /** - * The message payload, containing data pertaining to this connection step. + * A URL of an image that can be used to display this channel. */ - payload?: { [key: string]: any }; + glyph?: string; /** - * Identifies the type of the connection step message. + * A user-readable name for this channel, e.g: `"Red"`. */ - type: ConnectionStepMessageType; + name?: string; } /** - * Metadata for a Web Connection Protocol message. + * Uniquely defines each channel type. + * Can be "user", "app" or "private". */ -export interface ConnectionStepMetadata { - timestamp: Date; - connectionAttemptUuid?: string; -} +export type Type = 'app' | 'private' | 'user'; /** - * Identifies the type of the connection step message. + * 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. */ -export type ConnectionStepMessageType = - | 'WCP1Hello' - | 'WCP2LoadUrl' - | 'WCP3Handshake' - | 'WCP4ValidateAppIdentity' - | 'WCP5ValidateAppIdentityFailedResponse' - | 'WCP5ValidateAppIdentityResponse' - | 'WCP6Goodbye'; /** - * A request to add a context listener to a specified Channel OR to the current user - * channel. Where the listener is added to the current user channel (channelId == null), and - * this app has already been added to a user channel, client code should make a subsequent - * request to get the current context of that channel for this listener and then call its - * handler with it. + * A request to unsubscribe an event listener. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface AddContextListenerRequest { +export interface EventListenerUnsubscribeRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -636,90 +1036,19 @@ export interface AddContextListenerRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: AddContextListenerRequestPayload; + payload: EventListenerUnsubscribeRequestPayload; /** * 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. */ - type: 'addContextListenerRequest'; -} - -/** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. - */ -export interface AddContextListenerRequestMeta { - requestUuid: string; - /** - * Field that represents the source application that a request or response was received - * from. Please note that this may be set by an app or Desktop Agent proxy for debugging - * purposes but a Desktop Agent should make its own determination of the source of a message - * to avoid spoofing. - */ - source?: AppIdentifier; - timestamp: Date; -} - -/** - * Field that represents the source application that a request or response was received - * from. Please note that this may be set by an app or Desktop Agent proxy for debugging - * purposes but a Desktop Agent should make its own determination of the source of a message - * to avoid spoofing. - * - * Identifies an application, or instance of an application, and is used to target FDC3 API - * calls, such as `fdc3.open` or `fdc3.raiseIntent` at specific applications or application - * instances. - * - * Will always include at least an `appId` field, which uniquely identifies a specific app. - * - * If the `instanceId` field is set then the `AppMetadata` object represents a specific - * instance of the application that may be addressed using that Id. - * - * Field that represents the source application that the request being responded to was - * received from, for debugging purposes. - * - * Details of the application instance that broadcast the context. - * - * The App resolution option chosen. - * - * Details of the application instance that raised the intent. - * - * Identifier for the app instance that was selected (or started) to resolve the intent. - * `source.instanceId` MUST be set, indicating the specific app instance that - * received the intent. - */ -export interface AppIdentifier { - /** - * The unique application identifier located within a specific application directory - * instance. An example of an appId might be 'app@sub.root'. - */ - appId: string; - /** - * The Desktop Agent that the app is available on. Used in Desktop Agent Bridging to - * identify the Desktop Agent to target. - */ - desktopAgent?: string; - /** - * An optional instance identifier, indicating that this object represents a specific - * instance of the application described. - */ - instanceId?: string; - [property: string]: any; + type: 'eventListenerUnsubscribeRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface AddContextListenerRequestPayload { - /** - * The id of the channel to add the listener to or `null` indicating that it should listen - * to the current user channel (at the time of broadcast). - */ - channelId: null | string; - /** - * The type of context to listen for OR `null` indicating that it should listen to all - * context types. - */ - contextType: null | string; +export interface EventListenerUnsubscribeRequestPayload { + listenerUUID: string; } /** @@ -728,15 +1057,12 @@ export interface AddContextListenerRequestPayload { */ /** - * A response to a addContextListener request. Where the listener was added to the current - * user channel (channelId == null), and this app has already been added to a user channel, - * client code should make a subsequent request to get the current context of that channel - * for this listener and then call its handler with it. + * A response to an eventListenerUnsubscribe request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface AddContextListenerResponse { +export interface EventListenerUnsubscribeResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -746,686 +1072,599 @@ export interface AddContextListenerResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: AddContextListenerResponsePayload; + payload: BroadcastResponseResponsePayload; /** * 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. */ - type: 'addContextListenerResponse'; + type: 'eventListenerUnsubscribeResponse'; } /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * 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. */ -export interface AddContextListenerResponseMeta { - requestUuid: string; - responseUuid: string; - /** - * Field that represents the source application that the request being responded to was - * received from, for debugging purposes. - */ - source?: AppIdentifier; - timestamp: Date; -} /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * Setup message sent by the DA proxy code in getAgent() to a channel selector UI in an + * iframe with the channel definitions and current channel selection. + * + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. */ -export interface AddContextListenerResponsePayload { - error?: PurpleError; - listenerUUID?: string; +export interface Fdc3UserInterfaceChannels { + /** + * The message payload. + */ + payload: Fdc3UserInterfaceChannelsPayload; + /** + * Identifies the type of the message to or from the user interface frame. + */ + type: 'Fdc3UserInterfaceChannels'; } /** - * 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`). + * The message payload. */ -export type PurpleError = 'AccessDenied' | 'CreationFailed' | 'MalformedContext' | 'NoChannelFound'; +export interface Fdc3UserInterfaceChannelsPayload { + /** + * The id of the channel that should be currently selected, or `null` if none should be + * selected. + */ + selected: null | string; + /** + * User Channel definitions.```````s + */ + userChannels: Channel[]; +} /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ /** - * A request to add an event listener for a specified event type to the Desktop Agent. + * Message from a channel selector UI to the DA proxy sent when the channel selection + * changes. * - * A request message from an FDC3-enabled app to a Desktop Agent. - */ -export interface AddEventListenerRequest { - /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. - */ - meta: AddContextListenerRequestMeta; + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. + */ +export interface Fdc3UserInterfaceChannelSelected { /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload. */ - payload: AddEventListenerRequestPayload; + payload: Fdc3UserInterfaceChannelSelectedPayload; /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ - type: 'addEventListenerRequest'; + type: 'Fdc3UserInterfaceChannelSelected'; } /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload. */ -export interface AddEventListenerRequestPayload { +export interface Fdc3UserInterfaceChannelSelectedPayload { /** - * The type of the event to be listened to or `null` to listen to all event types. + * The id of the channel that should be currently selected, or `null` if none should be + * selected. */ - type: 'USER_CHANNEL_CHANGED' | null; + selected: null | string; } /** - * The type of a (non-context and non-intent) event that may be received via the FDC3 API's - * addEventListener function. - */ - -/** - * 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. + * Identifies the type of the message to or from the user interface frame. */ /** - * A response to an addEventListener request. + * Message from a UI iframe to the DA proxy (setup by `getAgent()`) indicating that the user + * is dragging the UI to a new location and providing the offset to apply to the location. + * The DA proxy implementation should limit the location to the current bounds of the + * window's viewport. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. */ -export interface AddEventListenerResponse { - /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. - */ - meta: AddContextListenerResponseMeta; +export interface Fdc3UserInterfaceDrag { /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload. */ - payload: AddEventListenerResponsePayload; + payload: Fdc3UserInterfaceDragPayload; /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ - type: 'addEventListenerResponse'; + type: 'Fdc3UserInterfaceDrag'; } /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload. */ -export interface AddEventListenerResponsePayload { - error?: ResponsePayloadError; - listenerUUID?: string; +export interface Fdc3UserInterfaceDragPayload { + /** + * The offset to move the frame by. + */ + mouseOffsets: MouseOffsets; } /** - * 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`). + * The offset to move the frame by. */ -export type ResponsePayloadError = - | 'AccessDenied' - | 'CreationFailed' - | 'MalformedContext' - | 'NoChannelFound' - | 'AppNotFound' - | 'AppTimeout' - | 'DesktopAgentNotFound' - | 'ErrorOnLaunch' - | 'ResolverUnavailable' - | 'IntentDeliveryFailed' - | 'NoAppsFound' - | 'ResolverTimeout' - | 'TargetAppUnavailable' - | 'TargetInstanceUnavailable' - | 'UserCancelledResolution' - | 'IntentHandlerRejected' - | 'NoResultReturned' - | 'AgentDisconnected' - | 'NotConnectedToBridge' - | 'ResponseToBridgeTimedOut' - | 'MalformedMessage'; +export interface MouseOffsets { + x: number; + y: number; +} /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ /** - * A request to add an Intent listener for a specified intent type. + * Handshake message sent back to a user interface from the DA proxy code (setup by + * `getAgent()`) over the `MessagePort` provided in the preceding Fdc3UserInterfaceHello + * message, confirming that it is listening to the `MessagePort` for further communication. * - * A request message from an FDC3-enabled app to a Desktop Agent. + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. */ -export interface AddIntentListenerRequest { - /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. - */ - meta: AddContextListenerRequestMeta; +export interface Fdc3UserInterfaceHandshake { /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload. */ - payload: AddIntentListenerRequestPayload; + payload: Fdc3UserInterfaceHandshakePayload; /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ - type: 'addIntentListenerRequest'; + type: 'Fdc3UserInterfaceHandshake'; } /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload. */ -export interface AddIntentListenerRequestPayload { +export interface Fdc3UserInterfaceHandshakePayload { /** - * The name of the intent to listen for. + * The version of FDC3 API that the Desktop Agent will provide support for. */ - intent: string; + fdc3Version: string; } /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ /** - * A response to a addIntentListener request. + * Hello message sent by a UI to the Desktop Agent proxy setup by `getAgent()` to indicate + * it is ready to communicate, containing initial CSS to set on the iframe, and including an + * appended `MessagePort` to be used for further communication. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. */ -export interface AddIntentListenerResponse { - /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. - */ - meta: AddContextListenerResponseMeta; +export interface Fdc3UserInterfaceHello { /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload. */ - payload: PayloadObject; + payload: Fdc3UserInterfaceHelloPayload; /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ - type: 'addIntentListenerResponse'; -} - -/** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - */ -export interface PayloadObject { - error?: FluffyError; - listenerUUID?: string; - [property: string]: any; + type: 'Fdc3UserInterfaceHello'; } /** - * 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`). - */ -export type FluffyError = - | 'MalformedContext' - | 'DesktopAgentNotFound' - | 'ResolverUnavailable' - | 'IntentDeliveryFailed' - | 'NoAppsFound' - | 'ResolverTimeout' - | 'TargetAppUnavailable' - | 'TargetInstanceUnavailable' - | 'UserCancelledResolution'; - -/** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. + * The message payload. */ -export interface AgentEventMessageMeta { - eventUuid: string; - timestamp: Date; +export interface Fdc3UserInterfaceHelloPayload { + /** + * Details about the UI implementation, such as vendor and version, for logging purposes. + */ + implementationDetails: string; + /** + * A constrained set of styling properties that should be set on the user interface before + * it is displayed. Note `position` cannot be specified and should always be set to `fixed`. + */ + initialCSS: InitialCSS; } /** - * 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. - */ -export type EventMessageType = - | 'addEventListenerEvent' - | 'broadcastEvent' - | 'channelChangedEvent' - | 'heartbeatEvent' - | 'intentEvent' - | 'privateChannelOnAddContextListenerEvent' - | 'privateChannelOnDisconnectEvent' - | 'privateChannelOnUnsubscribeEvent'; - -/** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * A constrained set of styling properties that should be set on the user interface before + * it is displayed. Note `position` cannot be specified and should always be set to `fixed`. */ -export interface AgentResponseMessageMeta { - requestUuid: string; - responseUuid: string; +export interface InitialCSS { + /** + * The initial bottom property to apply to the iframe. + */ + bottom?: string; + /** + * The initial height of the iframe. + */ + height?: string; + /** + * The initial left property to apply to the iframe. + */ + left?: string; + /** + * The maximum height to apply to the iframe. + */ + maxHeight?: string; + /** + * The maximum with to apply to the iframe. + */ + maxWidth?: string; + /** + * The initial right property to apply to the iframe. + */ + right?: string; + /** + * The initial top property to apply to the iframe. + */ + top?: string; /** - * Field that represents the source application that the request being responded to was - * received from, for debugging purposes. + * The transition property to apply to the iframe. */ - source?: AppIdentifier; - timestamp: Date; -} - -/** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - */ -export interface AgentResponseMessageResponsePayload { - error?: ResponsePayloadError; + transition?: string; + /** + * The initial width of the iframe. + */ + width?: string; + /** + * The initial zindex to apply to the iframe. + */ + zIndex?: string; [property: string]: any; } /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ -export type ResponseMessageType = - | 'addContextListenerResponse' - | 'addEventListenerResponse' - | 'addIntentListenerResponse' - | 'broadcastResponse' - | 'contextListenerUnsubscribeResponse' - | 'createPrivateChannelResponse' - | 'eventListenerUnsubscribeResponse' - | 'findInstancesResponse' - | 'findIntentResponse' - | 'findIntentsByContextResponse' - | 'getAppMetadataResponse' - | 'getCurrentChannelResponse' - | 'getCurrentContextResponse' - | 'getInfoResponse' - | 'getOrCreateChannelResponse' - | 'getUserChannelsResponse' - | 'intentListenerUnsubscribeResponse' - | 'intentResultResponse' - | 'joinUserChannelResponse' - | 'leaveCurrentChannelResponse' - | 'openResponse' - | 'privateChannelAddEventListenerResponse' - | 'privateChannelDisconnectResponse' - | 'privateChannelUnsubscribeEventListenerResponse' - | 'raiseIntentForContextResponse' - | 'raiseIntentResponse' - | 'raiseIntentResultResponse'; /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. */ -export interface AppRequestMessageMeta { - requestUuid: string; +export interface Fdc3UserInterfaceMessage { /** - * Field that represents the source application that a request or response was received - * from. Please note that this may be set by an app or Desktop Agent proxy for debugging - * purposes but a Desktop Agent should make its own determination of the source of a message - * to avoid spoofing. + * The message payload. */ - source?: AppIdentifier; - timestamp: Date; + payload?: { [key: string]: any }; + /** + * Identifies the type of the message to or from the user interface frame. + */ + type: Fdc3UserInterfaceMessageType; } /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ -export type RequestMessageType = - | 'addContextListenerRequest' - | 'addEventListenerRequest' - | 'addIntentListenerRequest' - | 'broadcastRequest' - | 'contextListenerUnsubscribeRequest' - | 'createPrivateChannelRequest' - | 'eventListenerUnsubscribeRequest' - | 'findInstancesRequest' - | 'findIntentRequest' - | 'findIntentsByContextRequest' - | 'getAppMetadataRequest' - | 'getCurrentChannelRequest' - | 'getCurrentContextRequest' - | 'getInfoRequest' - | 'getOrCreateChannelRequest' - | 'getUserChannelsRequest' - | 'heartbeatAcknowledgementRequest' - | 'intentListenerUnsubscribeRequest' - | 'intentResultRequest' - | 'joinUserChannelRequest' - | 'leaveCurrentChannelRequest' - | 'openRequest' - | 'privateChannelAddEventListenerRequest' - | 'privateChannelDisconnectRequest' - | 'privateChannelUnsubscribeEventListenerRequest' - | 'raiseIntentForContextRequest' - | 'raiseIntentRequest'; +export type Fdc3UserInterfaceMessageType = + | 'Fdc3UserInterfaceHello' + | 'Fdc3UserInterfaceHandshake' + | 'Fdc3UserInterfaceRestyle' + | 'Fdc3UserInterfaceDrag' + | 'Fdc3UserInterfaceResolve' + | 'Fdc3UserInterfaceResolveAction' + | 'Fdc3UserInterfaceChannels' + | 'Fdc3UserInterfaceChannelSelected'; /** - * An event message from the Desktop Agent to an app indicating that context has been - * broadcast on a channel it is listening to, or specifically to this app instance if it was - * launched via `fdc3.open` and context was passed. + * Setup message sent by the DA proxy code in getAgent() to an intent resolver UI with the + * resolver data to setup the UI. * - * A message from a Desktop Agent to an FDC3-enabled app representing an event. + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. */ -export interface BroadcastEvent { - /** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. - */ - meta: BroadcastEventMeta; +export interface Fdc3UserInterfaceResolve { /** - * The message payload contains details of the event that the app is being notified about. + * The message payload. */ - payload: BroadcastEventPayload; + payload: Fdc3UserInterfaceResolvePayload; /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ - type: 'broadcastEvent'; + type: 'Fdc3UserInterfaceResolve'; } /** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. + * The message payload. */ -export interface BroadcastEventMeta { - eventUuid: string; - timestamp: Date; +export interface Fdc3UserInterfaceResolvePayload { + /** + * An array of AppIntent objects defining the resolution options. + */ + appIntents: AppIntent[]; + context: Context; } /** - * The message payload contains details of the event that the app is being notified about. + * An interface that relates an intent to apps. + * + * Used if a raiseIntent request requires additional resolution (e.g. by showing an intent + * resolver) before it can be handled. */ -export interface BroadcastEventPayload { - /** - * The Id of the channel that the broadcast was sent on. May be `null` if the context is - * being broadcast due to a call `fdc3.open` that passed context. - */ - channelId: null | string; +export interface AppIntent { /** - * The context object that was broadcast. + * Details of applications that can resolve the intent. */ - context: Context; + apps: AppMetadata[]; /** - * Details of the application instance that broadcast the context. + * Details of the intent whose relationship to resolving applications is being described. */ - originatingApp?: AppIdentifier; + intent: IntentMetadata; } /** - * The context object that was broadcast. - * - * The context object that is to be broadcast. - * - * The context object passed with the raised intent. - * - * If a Context object is passed in, this object will be provided to the opened application - * via a contextListener. The Context argument is functionally equivalent to opening the - * target app with no context and broadcasting the context directly to it. + * Extends an `AppIdentifier`, describing an application or instance of an application, with + * additional descriptive metadata that is usually provided by an FDC3 App Directory that + * the Desktop Agent connects to. * - * The `fdc3.context` type defines the basic contract or "shape" for all data exchanged by - * FDC3 operations. As such, it is not really meant to be used on its own, but is imported - * by more specific type definitions (standardized or custom) to provide the structure and - * properties shared by all FDC3 context data types. + * The additional information from an app directory can aid in rendering UI elements, such + * as a launcher menu or resolver UI. This includes a title, description, tooltip and icon + * and screenshot URLs. * - * The key element of FDC3 context types is their mandatory `type` property, which is used - * to identify what type of data the object represents, and what shape it has. + * Note that as `AppMetadata` instances are also `AppIdentifiers` they may be passed to the + * `app` argument of `fdc3.open`, `fdc3.raiseIntent` etc. * - * The FDC3 context type, and all derived types, define the minimum set of fields a context - * data object of a particular type can be expected to have, but this can always be extended - * with custom fields as appropriate. + * The calling application instance's own metadata, according to the Desktop Agent (MUST + * include at least the `appId` and `instanceId`). */ -export interface Context { +export interface AppMetadata { /** - * Context data objects may include a set of equivalent key-value pairs that can be used to - * help applications identify and look up the context type they receive in their own domain. - * The idea behind this design is that applications can provide as many equivalent - * identifiers to a target application as possible, e.g. an instrument may be represented by - * an ISIN, CUSIP or Bloomberg identifier. - * - * Identifiers do not make sense for all types of data, so the `id` property is therefore - * optional, but some derived types may choose to require at least one identifier. - * Identifier values SHOULD always be of type string. + * The unique application identifier located within a specific application directory + * instance. An example of an appId might be 'app@sub.root'. + */ + appId: string; + /** + * A longer, multi-paragraph description for the application that could include markup. + */ + description?: string; + /** + * The Desktop Agent that the app is available on. Used in Desktop Agent Bridging to + * identify the Desktop Agent to target. + */ + desktopAgent?: string; + /** + * A list of icon URLs for the application that can be used to render UI elements. + */ + icons?: Icon[]; + /** + * An optional instance identifier, indicating that this object represents a specific + * instance of the application described. + */ + instanceId?: string; + /** + * An optional set of, implementation specific, metadata fields that can be used to + * disambiguate instances, such as a window title or screen position. Must only be set if + * `instanceId` is set. + */ + instanceMetadata?: { [key: string]: any }; + /** + * The 'friendly' app name. + * This field was used with the `open` and `raiseIntent` calls in FDC3 <2.0, which now + * require an `AppIdentifier` wth `appId` set. + * Note that for display purposes the `title` field should be used, if set, in preference to + * this field. + */ + name?: string; + /** + * The type of output returned for any intent specified during resolution. May express a + * particular context type (e.g. "fdc3.instrument"), channel (e.g. "channel") or a channel + * that will receive a specified type (e.g. "channel"). + */ + resultType?: null | string; + /** + * Images representing the app in common usage scenarios that can be used to render UI + * elements. + */ + screenshots?: Image[]; + /** + * A more user-friendly application title that can be used to render UI elements. */ - id?: { [key: string]: any }; + title?: string; /** - * Context data objects may include a name property that can be used for more information, - * or display purposes. Some derived types may require the name object as mandatory, - * depending on use case. + * A tooltip for the application that can be used to render UI elements. */ - name?: string; + tooltip?: string; /** - * The type property is the only _required_ part of the FDC3 context data schema. The FDC3 - * [API](https://fdc3.finos.org/docs/api/spec) relies on the `type` property being present - * to route shared context data appropriately. - * - * FDC3 [Intents](https://fdc3.finos.org/docs/intents/spec) also register the context data - * types they support in an FDC3 [App - * Directory](https://fdc3.finos.org/docs/app-directory/overview), used for intent discovery - * and routing. - * - * Standardized FDC3 context types have well-known `type` properties prefixed with the - * `fdc3` namespace, e.g. `fdc3.instrument`. For non-standard types, e.g. those defined and - * used by a particular organization, the convention is to prefix them with an - * organization-specific namespace, e.g. `blackrock.fund`. - * - * See the [Context Data Specification](https://fdc3.finos.org/docs/context/spec) for more - * information about context data types. + * The Version of the application. */ - type: string; - [property: string]: any; + version?: string; } /** - * 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. - */ - -/** - * A request to broadcast context on a channel. - * - * A request message from an FDC3-enabled app to a Desktop Agent. + * Describes an Icon image that may be used to represent the application. */ -export interface BroadcastRequest { +export interface Icon { /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + * The icon dimension, formatted as `x`. */ - meta: AddContextListenerRequestMeta; + size?: string; /** - * The message payload typically contains the arguments to FDC3 API functions. + * The icon url. */ - payload: BroadcastRequestPayload; + src: string; /** - * 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. + * Icon media type. If not present the Desktop Agent may use the src file extension. */ - type: 'broadcastRequest'; + type?: string; } /** - * The message payload typically contains the arguments to FDC3 API functions. + * Describes an image file, typically a screenshot, that often represents the application in + * a common usage scenario. */ -export interface BroadcastRequestPayload { +export interface Image { /** - * The Id of the Channel that the broadcast was sent on. + * Caption for the image. */ - channelId: string; + label?: string; /** - * The context object that is to be broadcast. + * The image dimension, formatted as `x`. */ - context: Context; + size?: string; + /** + * The image url. + */ + src: string; + /** + * Image media type. If not present the Desktop Agent may use the src file extension. + */ + type?: string; } /** - * 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. - */ - -/** - * A response to a request to broadcast context on a channel. + * Details of the intent whose relationship to resolving applications is being described. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * Metadata describing an Intent. */ -export interface BroadcastResponse { - /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. - */ - meta: AddContextListenerResponseMeta; +export interface IntentMetadata { /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * Display name for the intent. */ - payload: BroadcastResponseResponsePayload; + displayName?: string; /** - * 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. + * The unique name of the intent that can be invoked by the raiseIntent call. */ - type: 'broadcastResponse'; -} - -/** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - */ -export interface BroadcastResponseResponsePayload { - error?: ResponsePayloadError; - [property: string]: any; + name: string; } /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ /** - * An event message from the Desktop Agent to an app indicating that its current user - * channel has changed. + * Message from an intent resolver UI to DA proxy code in getAgent() reporting a user + * action. * - * A message from a Desktop Agent to an FDC3-enabled app representing an event. + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. */ -export interface ChannelChangedEvent { - /** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. - */ - meta: BroadcastEventMeta; +export interface Fdc3UserInterfaceResolveAction { /** - * The message payload contains details of the event that the app is being notified about. + * The message payload. */ - payload: ChannelChangedEventPayload; + payload: Fdc3UserInterfaceResolveActionPayload; /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ - type: 'channelChangedEvent'; + type: 'Fdc3UserInterfaceResolveAction'; } /** - * The message payload contains details of the event that the app is being notified about. + * The message payload. */ -export interface ChannelChangedEventPayload { +export interface Fdc3UserInterfaceResolveActionPayload { + action: Action; /** - * The Id of the channel that the app was added to or `null` if it was removed from a - * channel. + * The App resolution option chosen. */ - newChannelId: null | string; + appIdentifier?: AppIdentifier; + /** + * The intent resolved. + */ + intent?: string; } +export type Action = 'hover' | 'click' | 'cancel'; + /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ /** - * A request to unsubscribe a context listener. + * Message from a UI frame to the DA proxy code (setup by `getAgent()`) with updated styling + * information to apply to it. Can be used to implement a pop-open or close interaction or + * other transition needed by a UI implementation. * - * A request message from an FDC3-enabled app to a Desktop Agent. + * A message used to communicate with user interface frames injected by `getAgent()` for + * displaying UI elements such as the intent resolver or channel selector. Used for messages + * sent in either direction. */ -export interface ContextListenerUnsubscribeRequest { - /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. - */ - meta: AddContextListenerRequestMeta; +export interface Fdc3UserInterfaceRestyle { /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload. */ - payload: ContextListenerUnsubscribeRequestPayload; + payload: Fdc3UserInterfaceRestylePayload; /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ - type: 'contextListenerUnsubscribeRequest'; + type: 'Fdc3UserInterfaceRestyle'; } /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload. */ -export interface ContextListenerUnsubscribeRequestPayload { - listenerUUID: string; +export interface Fdc3UserInterfaceRestylePayload { + /** + * A constrained set of styling properties that should be applied to the frame. Note + * `position` cannot be set, and should always be `fixed`. + */ + updatedCSS: UpdatedCSS; } /** - * 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. - */ - -/** - * A response to a contextListenerUnsubscribe request. - * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A constrained set of styling properties that should be applied to the frame. Note + * `position` cannot be set, and should always be `fixed`. */ -export interface ContextListenerUnsubscribeResponse { +export interface UpdatedCSS { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * The initial bottom property to apply to the iframe. */ - meta: AddContextListenerResponseMeta; + bottom?: string; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The updated height of the iframe. */ - payload: BroadcastResponseResponsePayload; + height?: string; /** - * 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. + * The initial left property to apply to the iframe. */ - type: 'contextListenerUnsubscribeResponse'; + left?: string; + /** + * The updated maximum height to apply to the iframe. + */ + maxHeight?: string; + /** + * The updated maximum with to apply to the iframe. + */ + maxWidth?: string; + /** + * The initial right property to apply to the iframe. + */ + right?: string; + /** + * The initial top property to apply to the iframe. + */ + top?: string; + /** + * The updated transition property to apply to the iframe. + */ + transition?: string; + /** + * The updated width of the iframe. + */ + width?: string; + /** + * The updated zIndex to apply to the iframe. + */ + zIndex?: string; + [property: string]: any; } /** - * 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. + * Identifies the type of the message to or from the user interface frame. */ /** - * Request to return a Channel with an auto-generated identity that is intended for private - * communication between applications. + * A request for details of instances of a particular app. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface CreatePrivateChannelRequest { +export interface FindInstancesRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -1433,18 +1672,20 @@ export interface CreatePrivateChannelRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: CreatePrivateChannelRequestPayload; + payload: FindInstancesRequestPayload; /** * 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. */ - type: 'createPrivateChannelRequest'; + type: 'findInstancesRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface CreatePrivateChannelRequestPayload {} +export interface FindInstancesRequestPayload { + app: AppIdentifier; +} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -1452,12 +1693,12 @@ export interface CreatePrivateChannelRequestPayload {} */ /** - * A response to a createPrivateChannel request. + * A response to a findInstances request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface CreatePrivateChannelResponse { +export interface FindInstancesResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -1467,88 +1708,67 @@ export interface CreatePrivateChannelResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: CreatePrivateChannelResponsePayload; + payload: FindInstancesResponsePayload; /** * 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. */ - type: 'createPrivateChannelResponse'; + type: 'findInstancesResponse'; } /** * A payload for a response to an API call that will contain any return values or an `error` * property containing a standardized error message indicating that the request was * unsuccessful. - */ -export interface CreatePrivateChannelResponsePayload { - error?: PurpleError; - privateChannel?: Channel; -} - -/** - * Represents a context channel that applications can use to send and receive - * context data. * - * Please note that There are differences in behavior when you interact with a - * User channel via the `DesktopAgent` interface and the `Channel` interface. - * Specifically, when 'joining' a User channel or adding a context listener - * when already joined to a channel via the `DesktopAgent` interface, existing - * context (matching the type of the context listener) on the channel is - * received by the context listener immediately. Whereas, when a context - * listener is added via the Channel interface, context is not received - * automatically, but may be retrieved manually via the `getCurrentContext()` - * function. + * The message payload contains a flag indicating whether the API call was successful, plus + * any return values for the FDC3 API function called, or indicating that the request + * resulted in an error and including a standardized error message. */ -export interface Channel { - /** - * Channels may be visualized and selectable by users. DisplayMetadata may be used to - * provide hints on how to see them. - * For App channels, displayMetadata would typically not be present. - */ - displayMetadata?: DisplayMetadata; - /** - * Constant that uniquely identifies this channel. - */ - id: string; - /** - * Uniquely defines each channel type. - * Can be "user", "app" or "private". - */ - type: Type; +export interface FindInstancesResponsePayload { + error?: FindInstancesErrors; + appIdentifiers?: AppMetadata[]; } /** - * Channels may be visualized and selectable by users. DisplayMetadata may be used to - * provide hints on how to see them. - * For App channels, displayMetadata would typically not be present. + * Constants representing the errors that can be encountered when calling the `open` method + * on the DesktopAgent object (`fdc3`). * - * A system channel will be global enough to have a presence across many apps. This gives us - * some hints - * to render them in a standard way. It is assumed it may have other properties too, but if - * it has these, - * this is their meaning. - */ -export interface DisplayMetadata { - /** - * The color that should be associated within this channel when displaying this channel in a - * UI, e.g: `0xFF0000`. - */ - color?: string; - /** - * A URL of an image that can be used to display this channel. - */ - glyph?: string; - /** - * A user-readable name for this channel, e.g: `"Red"`. - */ - name?: string; -} - -/** - * Uniquely defines each channel type. - * Can be "user", "app" or "private". + * Constants representing the errors that can be encountered when calling the `findIntent`, + * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the + * DesktopAgent (`fdc3`). + * + * Unique identifier for a request or event message. Required in all message types. + * + * Unique identifier for a response to a specific message and must always be accompanied by + * a RequestUuid. + * + * Unique identifier for a `listener` object returned by a Desktop Agent to an app in + * response to addContextListener, addIntentListener or one of the PrivateChannel event + * listeners and used to identify it in messages (e.g. when unsubscribing). + * + * Unique identifier for an event message sent from a Desktop Agent to an app. + * + * Unique identifier for a for an attempt to connect to a Desktop Agent. A Unique UUID + * should be used in the first (WCP1Hello) message and should be quoted in all subsequent + * messages to link them to the same connection attempt. + * + * Should be set if the raiseIntent request returned an error. */ -export type Type = 'app' | 'private' | 'user'; +export type FindInstancesErrors = + | 'MalformedContext' + | 'DesktopAgentNotFound' + | 'ResolverUnavailable' + | 'IntentDeliveryFailed' + | 'NoAppsFound' + | 'ResolverTimeout' + | 'TargetAppUnavailable' + | 'TargetInstanceUnavailable' + | 'UserCancelledResolution' + | 'AgentDisconnected' + | 'NotConnectedToBridge' + | 'ResponseToBridgeTimedOut' + | 'MalformedMessage'; /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -1556,11 +1776,11 @@ export type Type = 'app' | 'private' | 'user'; */ /** - * A request to unsubscribe an event listener. + * A request for details of apps available to resolve a particular intent and context pair. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface EventListenerUnsubscribeRequest { +export interface FindIntentRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -1568,19 +1788,21 @@ export interface EventListenerUnsubscribeRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: EventListenerUnsubscribeRequestPayload; + payload: FindIntentRequestPayload; /** * 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. */ - type: 'eventListenerUnsubscribeRequest'; + type: 'findIntentRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface EventListenerUnsubscribeRequestPayload { - listenerUUID: string; +export interface FindIntentRequestPayload { + context?: Context; + intent: string; + resultType?: string; } /** @@ -1589,12 +1811,12 @@ export interface EventListenerUnsubscribeRequestPayload { */ /** - * A response to an eventListenerUnsubscribe request. + * A response to a findIntent request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface EventListenerUnsubscribeResponse { +export interface FindIntentResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -1604,480 +1826,339 @@ export interface EventListenerUnsubscribeResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: BroadcastResponseResponsePayload; + payload: FindIntentResponsePayload; /** * 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. */ - type: 'eventListenerUnsubscribeResponse'; -} - -/** - * 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. - */ - -/** - * Message from a channel selector UI to the DA proxy sent when the channel selection - * changes. - * - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. - */ -export interface Fdc3UserInterfaceChannelSelected { - /** - * The message payload. - */ - payload: Fdc3UserInterfaceChannelSelectedPayload; - /** - * Identifies the type of the message to or from the user interface frame. - */ - type: 'Fdc3UserInterfaceChannelSelected'; -} - -/** - * The message payload. - */ -export interface Fdc3UserInterfaceChannelSelectedPayload { - /** - * The id of the channel that should be currently selected, or `null` if none should be - * selected. - */ - selected: null | string; -} - -/** - * Identifies the type of the message to or from the user interface frame. - */ - -/** - * Setup message sent by the DA proxy code in getAgent() to a channel selector UI in an - * iframe with the channel definitions and current channel selection. - * - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. - */ -export interface Fdc3UserInterfaceChannels { - /** - * The message payload. - */ - payload: Fdc3UserInterfaceChannelsPayload; - /** - * Identifies the type of the message to or from the user interface frame. - */ - type: 'Fdc3UserInterfaceChannels'; + type: 'findIntentResponse'; } /** - * The message payload. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface Fdc3UserInterfaceChannelsPayload { - /** - * The id of the channel that should be currently selected, or `null` if none should be - * selected. - */ - selected: null | string; - /** - * User Channel definitions.```````s - */ - userChannels: Channel[]; +export interface FindIntentResponsePayload { + error?: FindInstancesErrors; + appIntent?: AppIntent; } /** - * Identifies the type of the message to or from the user interface frame. + * 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. */ /** - * Message from a UI iframe to the DA proxy (setup by `getAgent()`) indicating that the user - * is dragging the UI to a new location and providing the offset to apply to the location. - * The DA proxy implementation should limit the location to the current bounds of the - * window's viewport. + * A request for details of intents and apps available to resolve them for a particular + * context. * - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. + * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface Fdc3UserInterfaceDrag { +export interface FindIntentsByContextRequest { /** - * The message payload. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - payload: Fdc3UserInterfaceDragPayload; + meta: AddContextListenerRequestMeta; /** - * Identifies the type of the message to or from the user interface frame. + * The message payload typically contains the arguments to FDC3 API functions. */ - type: 'Fdc3UserInterfaceDrag'; -} - -/** - * The message payload. - */ -export interface Fdc3UserInterfaceDragPayload { + payload: FindIntentsByContextRequestPayload; /** - * The offset to move the frame by. + * 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. */ - mouseOffsets: MouseOffsets; + type: 'findIntentsByContextRequest'; } /** - * The offset to move the frame by. + * The message payload typically contains the arguments to FDC3 API functions. */ -export interface MouseOffsets { - x: number; - y: number; +export interface FindIntentsByContextRequestPayload { + context: Context; + resultType?: string; } /** - * Identifies the type of the message to or from the user interface frame. + * 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. */ /** - * Handshake message sent back to a user interface from the DA proxy code (setup by - * `getAgent()`) over the `MessagePort` provided in the preceding Fdc3UserInterfaceHello - * message, confirming that it is listening to the `MessagePort` for further communication. + * A response to a findIntentsByContext request. * - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. */ -export interface Fdc3UserInterfaceHandshake { +export interface FindIntentsByContextResponse { /** - * The message payload. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - payload: Fdc3UserInterfaceHandshakePayload; + meta: AddContextListenerResponseMeta; /** - * Identifies the type of the message to or from the user interface frame. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ - type: 'Fdc3UserInterfaceHandshake'; + payload: FindIntentsByContextResponsePayload; + /** + * 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. + */ + type: 'findIntentsByContextResponse'; } /** - * The message payload. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface Fdc3UserInterfaceHandshakePayload { - /** - * The version of FDC3 API that the Desktop Agent will provide support for. - */ - fdc3Version: string; +export interface FindIntentsByContextResponsePayload { + error?: FindInstancesErrors; + appIntents?: AppIntent[]; } /** - * Identifies the type of the message to or from the user interface frame. + * 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. */ /** - * Hello message sent by a UI to the Desktop Agent proxy setup by `getAgent()` to indicate - * it is ready to communicate, containing initial CSS to set on the iframe, and including an - * appended `MessagePort` to be used for further communication. + * A request for metadata about an app. * - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. + * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface Fdc3UserInterfaceHello { +export interface GetAppMetadataRequest { /** - * The message payload. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - payload: Fdc3UserInterfaceHelloPayload; + meta: AddContextListenerRequestMeta; /** - * Identifies the type of the message to or from the user interface frame. + * The message payload typically contains the arguments to FDC3 API functions. */ - type: 'Fdc3UserInterfaceHello'; + payload: GetAppMetadataRequestPayload; + /** + * 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. + */ + type: 'getAppMetadataRequest'; } /** - * The message payload. + * The message payload typically contains the arguments to FDC3 API functions. */ -export interface Fdc3UserInterfaceHelloPayload { - /** - * Details about the UI implementation, such as vendor and version, for logging purposes. - */ - implementationDetails: string; - /** - * A constrained set of styling properties that should be set on the user interface before - * it is displayed. Note `position` cannot be specified and should always be set to `fixed`. - */ - initialCSS: InitialCSS; +export interface GetAppMetadataRequestPayload { + app: AppIdentifier; } /** - * A constrained set of styling properties that should be set on the user interface before - * it is displayed. Note `position` cannot be specified and should always be set to `fixed`. + * 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. */ -export interface InitialCSS { - /** - * The initial bottom property to apply to the iframe. - */ - bottom?: string; - /** - * The initial height of the iframe. - */ - height?: string; - /** - * The initial left property to apply to the iframe. - */ - left?: string; - /** - * The maximum height to apply to the iframe. - */ - maxHeight?: string; - /** - * The maximum with to apply to the iframe. - */ - maxWidth?: string; - /** - * The initial right property to apply to the iframe. - */ - right?: string; - /** - * The initial top property to apply to the iframe. - */ - top?: string; + +/** + * A response to a getAppMetadata request. + * + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. + */ +export interface GetAppMetadataResponse { /** - * The transition property to apply to the iframe. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - transition?: string; + meta: AddContextListenerResponseMeta; /** - * The initial width of the iframe. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ - width?: string; + payload: GetAppMetadataResponsePayload; /** - * The initial zindex to apply to the iframe. + * 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. */ - zIndex?: string; - [property: string]: any; + type: 'getAppMetadataResponse'; } /** - * Identifies the type of the message to or from the user interface frame. - */ - -/** - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface Fdc3UserInterfaceMessage { - /** - * The message payload. - */ - payload?: { [key: string]: any }; - /** - * Identifies the type of the message to or from the user interface frame. - */ - type: Fdc3UserInterfaceMessageType; +export interface GetAppMetadataResponsePayload { + error?: FindInstancesErrors; + appMetadata?: AppMetadata; } /** - * Identifies the type of the message to or from the user interface frame. + * 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. */ -export type Fdc3UserInterfaceMessageType = - | 'Fdc3UserInterfaceHello' - | 'Fdc3UserInterfaceHandshake' - | 'Fdc3UserInterfaceRestyle' - | 'Fdc3UserInterfaceDrag' - | 'Fdc3UserInterfaceResolve' - | 'Fdc3UserInterfaceResolveAction' - | 'Fdc3UserInterfaceChannels' - | 'Fdc3UserInterfaceChannelSelected'; /** - * Setup message sent by the DA proxy code in getAgent() to an intent resolver UI with the - * resolver data to setup the UI. + * A request to return the Channel object for the current User channel membership. Returns + * `null` if the app is not joined to a channel. * - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. + * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface Fdc3UserInterfaceResolve { +export interface GetCurrentChannelRequest { /** - * The message payload. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - payload: Fdc3UserInterfaceResolvePayload; + meta: AddContextListenerRequestMeta; /** - * Identifies the type of the message to or from the user interface frame. + * The message payload typically contains the arguments to FDC3 API functions. */ - type: 'Fdc3UserInterfaceResolve'; + payload: GetCurrentChannelRequestPayload; + /** + * 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. + */ + type: 'getCurrentChannelRequest'; } /** - * The message payload. + * The message payload typically contains the arguments to FDC3 API functions. */ -export interface Fdc3UserInterfaceResolvePayload { - /** - * An array of AppIntent objects defining the resolution options. - */ - appIntents: AppIntent[]; - context: Context; -} +export interface GetCurrentChannelRequestPayload {} /** - * An interface that relates an intent to apps. + * 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. + */ + +/** + * A response to a getCurrentChannel request. * - * Used if a raiseIntent request requires additional resolution (e.g. by showing an intent - * resolver) before it can be handled. + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. */ -export interface AppIntent { +export interface GetCurrentChannelResponse { /** - * Details of applications that can resolve the intent. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - apps: AppMetadata[]; + meta: AddContextListenerResponseMeta; /** - * Details of the intent whose relationship to resolving applications is being described. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ - intent: IntentMetadata; + payload: GetCurrentChannelResponsePayload; + /** + * 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. + */ + type: 'getCurrentChannelResponse'; } /** - * Details of the intent whose relationship to resolving applications is being described. - * - * Metadata describing an Intent. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface IntentMetadata { - /** - * Display name for the intent. - */ - displayName?: string; - /** - * The unique name of the intent that can be invoked by the raiseIntent call. - */ - name: string; +export interface GetCurrentChannelResponsePayload { + error?: ResponsePayloadError; + channel?: Channel | null; } /** - * Identifies the type of the message to or from the user interface frame. + * 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. */ /** - * Message from an intent resolver UI to DA proxy code in getAgent() reporting a user - * action. + * A request to return the current context (either of a specified type or most recent + * broadcast) of a specified Channel. Returns `null` if no context (of the requested type if + * one was specified) is available in the channel. * - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. + * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface Fdc3UserInterfaceResolveAction { +export interface GetCurrentContextRequest { /** - * The message payload. + * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ - payload: Fdc3UserInterfaceResolveActionPayload; + meta: AddContextListenerRequestMeta; /** - * Identifies the type of the message to or from the user interface frame. + * The message payload typically contains the arguments to FDC3 API functions. */ - type: 'Fdc3UserInterfaceResolveAction'; + payload: GetCurrentContextRequestPayload; + /** + * 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. + */ + type: 'getCurrentContextRequest'; } /** - * The message payload. + * The message payload typically contains the arguments to FDC3 API functions. */ -export interface Fdc3UserInterfaceResolveActionPayload { - action: Action; +export interface GetCurrentContextRequestPayload { /** - * The App resolution option chosen. + * The id of the channel to return the current context of. */ - appIdentifier?: AppIdentifier; + channelId: string; /** - * The intent resolved. + * The type of context to return for OR `null` indicating that the most recently broadcast + * context on the channel should be returned. */ - intent?: string; + contextType: null | string; } -export type Action = 'hover' | 'click' | 'cancel'; - /** - * Identifies the type of the message to or from the user interface frame. + * 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. */ /** - * Message from a UI frame to the DA proxy code (setup by `getAgent()`) with updated styling - * information to apply to it. Can be used to implement a pop-open or close interaction or - * other transition needed by a UI implementation. + * A response to a getCurrentContext request. * - * A message used to communicate with user interface frames injected by `getAgent()` for - * displaying UI elements such as the intent resolver or channel selector. Used for messages - * sent in either direction. + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. */ -export interface Fdc3UserInterfaceRestyle { +export interface GetCurrentContextResponse { /** - * The message payload. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - payload: Fdc3UserInterfaceRestylePayload; + meta: AddContextListenerResponseMeta; /** - * Identifies the type of the message to or from the user interface frame. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ - type: 'Fdc3UserInterfaceRestyle'; -} - -/** - * The message payload. - */ -export interface Fdc3UserInterfaceRestylePayload { + payload: GetCurrentContextResponsePayload; /** - * A constrained set of styling properties that should be applied to the frame. Note - * `position` cannot be set, and should always be `fixed`. + * 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. */ - updatedCSS: UpdatedCSS; + type: 'getCurrentContextResponse'; } /** - * A constrained set of styling properties that should be applied to the frame. Note - * `position` cannot be set, and should always be `fixed`. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface UpdatedCSS { - /** - * The initial bottom property to apply to the iframe. - */ - bottom?: string; - /** - * The updated height of the iframe. - */ - height?: string; - /** - * The initial left property to apply to the iframe. - */ - left?: string; - /** - * The updated maximum height to apply to the iframe. - */ - maxHeight?: string; - /** - * The updated maximum with to apply to the iframe. - */ - maxWidth?: string; - /** - * The initial right property to apply to the iframe. - */ - right?: string; - /** - * The initial top property to apply to the iframe. - */ - top?: string; - /** - * The updated transition property to apply to the iframe. - */ - transition?: string; - /** - * The updated width of the iframe. - */ - width?: string; +export interface GetCurrentContextResponsePayload { + error?: PurpleError; /** - * The updated zIndex to apply to the iframe. + * The most recently broadcast context object (of the specified type, if one was specified), + * or `null` if none was available in the channel. */ - zIndex?: string; - [property: string]: any; + context?: null | Context; } /** - * Identifies the type of the message to or from the user interface frame. + * 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. */ /** - * A request for details of instances of a particular app. + * Request to retrieve information about the FDC3 Desktop Agent implementation and the + * metadata of the calling application according to the Desktop Agent. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface FindInstancesRequest { +export interface GetInfoRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2085,20 +2166,18 @@ export interface FindInstancesRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: FindInstancesRequestPayload; + payload: GetInfoRequestPayload; /** * 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. */ - type: 'findInstancesRequest'; + type: 'getInfoRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface FindInstancesRequestPayload { - app: AppIdentifier; -} +export interface GetInfoRequestPayload {} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -2106,12 +2185,12 @@ export interface FindInstancesRequestPayload { */ /** - * A response to a findInstances request. + * A response to a getInfo request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface FindInstancesResponse { +export interface GetInfoResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -2121,67 +2200,81 @@ export interface FindInstancesResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: FindInstancesResponsePayload; + payload: GetInfoResponsePayload; /** * 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. */ - type: 'findInstancesResponse'; + type: 'getInfoResponse'; } /** * A payload for a response to an API call that will contain any return values or an `error` * property containing a standardized error message indicating that the request was * unsuccessful. - * - * The message payload contains a flag indicating whether the API call was successful, plus - * any return values for the FDC3 API function called, or indicating that the request - * resulted in an error and including a standardized error message. */ -export interface FindInstancesResponsePayload { - error?: FindInstancesErrors; - appIdentifiers?: AppMetadata[]; +export interface GetInfoResponsePayload { + error?: ResponsePayloadError; + implementationMetadata?: ImplementationMetadata; } /** - * 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`). - * - * Unique identifier for a for an attempt to connect to a Desktop Agent. A Unique UUID - * should be used in the first (WCP1Hello) message and should be quoted in all subsequent - * messages to link them to the same connection attempt. - * - * Unique identifier for a request or event message. Required in all message types. - * - * Unique identifier for a response to a specific message and must always be accompanied by - * a RequestUuid. - * - * Unique identifier for a `listener` object returned by a Desktop Agent to an app in - * response to addContextListener, addIntentListener or one of the PrivateChannel event - * listeners and used to identify it in messages (e.g. when unsubscribing). + * Implementation metadata for the Desktop Agent, which includes an appMetadata element + * containing a copy of the app's own metadata. * - * Unique identifier for an event message sent from a Desktop Agent to an app. + * Includes Metadata for the current application. * - * Should be set if the raiseIntent request returned an error. + * Metadata relating to the FDC3 Desktop Agent implementation and its provider. */ -export type FindInstancesErrors = - | 'MalformedContext' - | 'DesktopAgentNotFound' - | 'ResolverUnavailable' - | 'IntentDeliveryFailed' - | 'NoAppsFound' - | 'ResolverTimeout' - | 'TargetAppUnavailable' - | 'TargetInstanceUnavailable' - | 'UserCancelledResolution' - | 'AgentDisconnected' - | 'NotConnectedToBridge' - | 'ResponseToBridgeTimedOut' - | 'MalformedMessage'; +export interface ImplementationMetadata { + /** + * The calling application instance's own metadata, according to the Desktop Agent (MUST + * include at least the `appId` and `instanceId`). + */ + appMetadata: AppMetadata; + /** + * The version number of the FDC3 specification that the implementation provides. + * The string must be a numeric semver version, e.g. 1.2 or 1.2.1. + */ + fdc3Version: string; + /** + * Metadata indicating whether the Desktop Agent implements optional features of + * the Desktop Agent API. + */ + optionalFeatures: OptionalFeatures; + /** + * The name of the provider of the Desktop Agent implementation (e.g. Finsemble, Glue42, + * OpenFin etc.). + */ + provider: string; + /** + * The version of the provider of the Desktop Agent implementation (e.g. 5.3.0). + */ + providerVersion?: string; +} + +/** + * Metadata indicating whether the Desktop Agent implements optional features of + * the Desktop Agent API. + */ +export interface OptionalFeatures { + /** + * Used to indicate whether the experimental Desktop Agent Bridging + * feature is implemented by the Desktop Agent. + */ + DesktopAgentBridging: boolean; + /** + * Used to indicate whether the exposure of 'originating app metadata' for + * context and intent messages is supported by the Desktop Agent. + */ + OriginatingAppMetadata: boolean; + /** + * Used to indicate whether the optional `fdc3.joinUserChannel`, + * `fdc3.getCurrentChannel` and `fdc3.leaveCurrentChannel` are implemented by + * the Desktop Agent. + */ + UserChannelMembershipAPIs: boolean; +} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -2189,11 +2282,12 @@ export type FindInstancesErrors = */ /** - * A request for details of apps available to resolve a particular intent and context pair. + * Request to return a Channel with an auto-generated identity that is intended for private + * communication between applications. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface FindIntentRequest { +export interface GetOrCreateChannelRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2201,21 +2295,22 @@ export interface FindIntentRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: FindIntentRequestPayload; + payload: GetOrCreateChannelRequestPayload; /** * 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. */ - type: 'findIntentRequest'; + type: 'getOrCreateChannelRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface FindIntentRequestPayload { - context?: Context; - intent: string; - resultType?: string; +export interface GetOrCreateChannelRequestPayload { + /** + * The id of the channel to return + */ + channelId: string; } /** @@ -2224,12 +2319,12 @@ export interface FindIntentRequestPayload { */ /** - * A response to a findIntent request. + * A response to a getOrCreateChannel request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface FindIntentResponse { +export interface GetOrCreateChannelResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -2239,12 +2334,12 @@ export interface FindIntentResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: FindIntentResponsePayload; + payload: GetOrCreateChannelResponsePayload; /** * 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. */ - type: 'findIntentResponse'; + type: 'getOrCreateChannelResponse'; } /** @@ -2252,9 +2347,9 @@ export interface FindIntentResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ -export interface FindIntentResponsePayload { - error?: FindInstancesErrors; - appIntent?: AppIntent; +export interface GetOrCreateChannelResponsePayload { + error?: PurpleError; + channel?: Channel; } /** @@ -2263,12 +2358,11 @@ export interface FindIntentResponsePayload { */ /** - * A request for details of intents and apps available to resolve them for a particular - * context. + * Request to retrieve a list of the User Channels available for the app to join. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface FindIntentsByContextRequest { +export interface GetUserChannelsRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2276,21 +2370,18 @@ export interface FindIntentsByContextRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: FindIntentsByContextRequestPayload; + payload: GetUserChannelsRequestPayload; /** * 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. */ - type: 'findIntentsByContextRequest'; + type: 'getUserChannelsRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface FindIntentsByContextRequestPayload { - context: Context; - resultType?: string; -} +export interface GetUserChannelsRequestPayload {} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -2298,12 +2389,12 @@ export interface FindIntentsByContextRequestPayload { */ /** - * A response to a findIntentsByContext request. + * A response to a getUserChannels request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface FindIntentsByContextResponse { +export interface GetUserChannelsResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -2313,12 +2404,12 @@ export interface FindIntentsByContextResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: FindIntentsByContextResponsePayload; + payload: GetUserChannelsResponsePayload; /** * 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. */ - type: 'findIntentsByContextResponse'; + type: 'getUserChannelsResponse'; } /** @@ -2326,9 +2417,9 @@ export interface FindIntentsByContextResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ -export interface FindIntentsByContextResponsePayload { - error?: FindInstancesErrors; - appIntents?: AppIntent[]; +export interface GetUserChannelsResponsePayload { + error?: PurpleError; + userChannels?: Channel[]; } /** @@ -2337,11 +2428,12 @@ export interface FindIntentsByContextResponsePayload { */ /** - * A request for metadata about an app. + * A request that serves as an acknowledgement of a heartbeat event from the Desktop Agent + * and indicates that an application window or frame is still alive. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface GetAppMetadataRequest { +export interface HeartbeatAcknowledgementRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2349,19 +2441,22 @@ export interface GetAppMetadataRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: GetAppMetadataRequestPayload; + payload: HeartbeatAcknowledgementRequestPayload; /** * 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. */ - type: 'getAppMetadataRequest'; + type: 'heartbeatAcknowledgementRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface GetAppMetadataRequestPayload { - app: AppIdentifier; +export interface HeartbeatAcknowledgementRequestPayload { + /** + * The eventUuid value of the HeartbeatEvent that the acknowledgement being sent relates to. + */ + heartbeatEventUuid: string; } /** @@ -2370,38 +2465,32 @@ export interface GetAppMetadataRequestPayload { */ /** - * A response to a getAppMetadata request. + * A heartbeat message from the Desktop Agent to an app indicating that the Desktop Agent is + * alive and that the application should send a heartbeatResponseRequest to the agent in + * response. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A message from a Desktop Agent to an FDC3-enabled app representing an event. */ -export interface GetAppMetadataResponse { +export interface HeartbeatEvent { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. */ - meta: AddContextListenerResponseMeta; + meta: BroadcastEventMeta; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload contains details of the event that the app is being notified about. */ - payload: GetAppMetadataResponsePayload; + payload: HeartbeatEventPayload; /** * 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. */ - type: 'getAppMetadataResponse'; + type: 'heartbeatEvent'; } /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload contains details of the event that the app is being notified about. */ -export interface GetAppMetadataResponsePayload { - error?: FindInstancesErrors; - appMetadata?: AppMetadata; -} +export interface HeartbeatEventPayload {} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -2409,69 +2498,48 @@ export interface GetAppMetadataResponsePayload { */ /** - * A request to return the Channel object for the current User channel membership. Returns - * `null` if the app is not joined to a channel. + * An event message from the Desktop Agent to an app indicating that it has been selected to + * resolve a raised intent and context. * - * A request message from an FDC3-enabled app to a Desktop Agent. + * A message from a Desktop Agent to an FDC3-enabled app representing an event. */ -export interface GetCurrentChannelRequest { +export interface IntentEvent { /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. */ - meta: AddContextListenerRequestMeta; + meta: BroadcastEventMeta; /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload contains details of the event that the app is being notified about. */ - payload: GetCurrentChannelRequestPayload; + payload: IntentEventPayload; /** * 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. + * the message relates to, e.g. 'findIntent', with 'Response' appended. */ - type: 'getCurrentChannelRequest'; + type: 'intentEvent'; } /** - * The message payload typically contains the arguments to FDC3 API functions. - */ -export interface GetCurrentChannelRequestPayload {} - -/** - * 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. - */ - -/** - * A response to a getCurrentChannel request. - * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * The message payload contains details of the event that the app is being notified about. */ -export interface GetCurrentChannelResponse { +export interface IntentEventPayload { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * The context object passed with the raised intent. */ - meta: AddContextListenerResponseMeta; + context: Context; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The intent that was raised. */ - payload: GetCurrentChannelResponsePayload; + intent: string; /** - * 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. + * Details of the application instance that raised the intent. */ - type: 'getCurrentChannelResponse'; -} - -/** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - */ -export interface GetCurrentChannelResponsePayload { - error?: ResponsePayloadError; - channel?: Channel | null; + originatingApp?: AppIdentifier; + /** + * The requestUuid value of the raiseIntentRequest that the intentEvent being sent relates + * to. + */ + raiseIntentRequestUuid: string; } /** @@ -2480,13 +2548,11 @@ export interface GetCurrentChannelResponsePayload { */ /** - * A request to return the current context (either of a specified type or most recent - * broadcast) of a specified Channel. Returns `null` if no context (of the requested type if - * one was specified) is available in the channel. + * A request to unsubscribe a context listener. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface GetCurrentContextRequest { +export interface IntentListenerUnsubscribeRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2494,27 +2560,19 @@ export interface GetCurrentContextRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: GetCurrentContextRequestPayload; + payload: IntentListenerUnsubscribeRequestPayload; /** * 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. */ - type: 'getCurrentContextRequest'; + type: 'intentListenerUnsubscribeRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface GetCurrentContextRequestPayload { - /** - * The id of the channel to return the current context of. - */ - channelId: string; - /** - * The type of context to return for OR `null` indicating that the most recently broadcast - * context on the channel should be returned. - */ - contextType: null | string; +export interface IntentListenerUnsubscribeRequestPayload { + listenerUUID: string; } /** @@ -2523,12 +2581,12 @@ export interface GetCurrentContextRequestPayload { */ /** - * A response to a getCurrentContext request. + * A response to a intentListenerUnsubscribe request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface GetCurrentContextResponse { +export interface IntentListenerUnsubscribeResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -2538,26 +2596,12 @@ export interface GetCurrentContextResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: GetCurrentContextResponsePayload; + payload: BroadcastResponseResponsePayload; /** * 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. */ - type: 'getCurrentContextResponse'; -} - -/** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - */ -export interface GetCurrentContextResponsePayload { - error?: PurpleError; - /** - * The most recently broadcast context object (of the specified type, if one was specified), - * or `null` if none was available in the channel. - */ - context?: null | Context; + type: 'intentListenerUnsubscribeResponse'; } /** @@ -2566,12 +2610,13 @@ export interface GetCurrentContextResponsePayload { */ /** - * Request to retrieve information about the FDC3 Desktop Agent implementation and the - * metadata of the calling application according to the Desktop Agent. + * A request to deliver a result for an intent (which may include a `void` result that just + * indicates that the handler has run, returning no result). The result is tied to the + * intentEvent it relates to by quoting the `eventUuid` of the intentEvent in its payload. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface GetInfoRequest { +export interface IntentResultRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2579,18 +2624,33 @@ export interface GetInfoRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: GetInfoRequestPayload; + payload: IntentResultRequestPayload; /** * 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. */ - type: 'getInfoRequest'; + type: 'intentResultRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface GetInfoRequestPayload {} +export interface IntentResultRequestPayload { + /** + * The eventUuid value of the intentEvent that the result being sent relates to. + */ + intentEventUuid: string; + intentResult: IntentResult; + /** + * The requestUuid value of the raiseIntentRequest that the result being sent relates to. + */ + raiseIntentRequestUuid: string; +} + +export interface IntentResult { + context?: Context; + channel?: Channel; +} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -2598,12 +2658,12 @@ export interface GetInfoRequestPayload {} */ /** - * A response to a getInfo request. + * A response to a request to deliver an intent result. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface GetInfoResponse { +export interface IntentResultResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -2613,22 +2673,12 @@ export interface GetInfoResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: GetInfoResponsePayload; + payload: BroadcastResponseResponsePayload; /** * 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. - */ - type: 'getInfoResponse'; -} - -/** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - */ -export interface GetInfoResponsePayload { - error?: ResponsePayloadError; - implementationMetadata?: ImplementationMetadata; + */ + type: 'intentResultResponse'; } /** @@ -2637,12 +2687,13 @@ export interface GetInfoResponsePayload { */ /** - * Request to return a Channel with an auto-generated identity that is intended for private - * communication between applications. + * Request to join the app to the specified User channel. On successfully joining a channel, + * client code should make subsequent requests to get the current context of that channel + * for all registered context listeners and then call their handlers with it. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface GetOrCreateChannelRequest { +export interface JoinUserChannelRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2650,20 +2701,20 @@ export interface GetOrCreateChannelRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: GetOrCreateChannelRequestPayload; + payload: JoinUserChannelRequestPayload; /** * 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. */ - type: 'getOrCreateChannelRequest'; + type: 'joinUserChannelRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface GetOrCreateChannelRequestPayload { +export interface JoinUserChannelRequestPayload { /** - * The id of the channel to return + * The id of the channel to join. */ channelId: string; } @@ -2674,12 +2725,14 @@ export interface GetOrCreateChannelRequestPayload { */ /** - * A response to a getOrCreateChannel request. + * A response to a joinUserChannel request. On receipt of this response, client code should + * make subsequent requests to get the current context of that channel for all registered + * context listeners and then call their handlers with it. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface GetOrCreateChannelResponse { +export interface JoinUserChannelResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -2689,12 +2742,12 @@ export interface GetOrCreateChannelResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: GetOrCreateChannelResponsePayload; + payload: JoinUserChannelResponsePayload; /** * 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. */ - type: 'getOrCreateChannelResponse'; + type: 'joinUserChannelResponse'; } /** @@ -2702,9 +2755,8 @@ export interface GetOrCreateChannelResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ -export interface GetOrCreateChannelResponsePayload { +export interface JoinUserChannelResponsePayload { error?: PurpleError; - channel?: Channel; } /** @@ -2713,11 +2765,11 @@ export interface GetOrCreateChannelResponsePayload { */ /** - * Request to retrieve a list of the User Channels available for the app to join. + * Request to remove the app from any User channel membership. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface GetUserChannelsRequest { +export interface LeaveCurrentChannelRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2725,18 +2777,18 @@ export interface GetUserChannelsRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: GetUserChannelsRequestPayload; + payload: LeaveCurrentChannelRequestPayload; /** * 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. */ - type: 'getUserChannelsRequest'; + type: 'leaveCurrentChannelRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface GetUserChannelsRequestPayload {} +export interface LeaveCurrentChannelRequestPayload {} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -2744,12 +2796,12 @@ export interface GetUserChannelsRequestPayload {} */ /** - * A response to a getUserChannels request. + * A response to a leaveCurrentChannel request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface GetUserChannelsResponse { +export interface LeaveCurrentChannelResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -2759,12 +2811,12 @@ export interface GetUserChannelsResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: GetUserChannelsResponsePayload; + payload: LeaveCurrentChannelResponsePayload; /** * 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. */ - type: 'getUserChannelsResponse'; + type: 'leaveCurrentChannelResponse'; } /** @@ -2772,9 +2824,8 @@ export interface GetUserChannelsResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ -export interface GetUserChannelsResponsePayload { +export interface LeaveCurrentChannelResponsePayload { error?: PurpleError; - userChannels?: Channel[]; } /** @@ -2783,12 +2834,11 @@ export interface GetUserChannelsResponsePayload { */ /** - * A request that serves as an acknowledgement of a heartbeat event from the Desktop Agent - * and indicates that an application window or frame is still alive. + * A request to open an application. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface HeartbeatAcknowledgementRequest { +export interface OpenRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2796,22 +2846,25 @@ export interface HeartbeatAcknowledgementRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: HeartbeatAcknowledgementRequestPayload; + payload: OpenRequestPayload; /** * 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. */ - type: 'heartbeatAcknowledgementRequest'; + type: 'openRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface HeartbeatAcknowledgementRequestPayload { +export interface OpenRequestPayload { + app: AppIdentifier; /** - * The eventUuid value of the HeartbeatEvent that the acknowledgement being sent relates to. + * If a Context object is passed in, this object will be provided to the opened application + * via a contextListener. The Context argument is functionally equivalent to opening the + * target app with no context and broadcasting the context directly to it. */ - heartbeatEventUuid: string; + context?: Context; } /** @@ -2820,82 +2873,58 @@ export interface HeartbeatAcknowledgementRequestPayload { */ /** - * A heartbeat message from the Desktop Agent to an app indicating that the Desktop Agent is - * alive and that the application should send a heartbeatResponseRequest to the agent in - * response. + * A response to a open request. * - * A message from a Desktop Agent to an FDC3-enabled app representing an event. + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. */ -export interface HeartbeatEvent { +export interface OpenResponse { /** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ - meta: BroadcastEventMeta; + meta: AddContextListenerResponseMeta; /** - * The message payload contains details of the event that the app is being notified about. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ - payload: HeartbeatEventPayload; + payload: OpenResponsePayload; /** * 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. */ - type: 'heartbeatEvent'; + type: 'openResponse'; } /** - * The message payload contains details of the event that the app is being notified about. - */ -export interface HeartbeatEventPayload {} - -/** - * 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. - */ - -/** - * An event message from the Desktop Agent to an app indicating that it has been selected to - * resolve a raised intent and context. - * - * A message from a Desktop Agent to an FDC3-enabled app representing an event. + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. */ -export interface IntentEvent { - /** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. - */ - meta: BroadcastEventMeta; - /** - * The message payload contains details of the event that the app is being notified about. - */ - payload: IntentEventPayload; - /** - * 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. - */ - type: 'intentEvent'; +export interface OpenResponsePayload { + error?: OpenErrorResponsePayload; + appIdentifier?: AppIdentifier; } /** - * The message payload contains details of the event that the app is being notified about. + * 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`). */ -export interface IntentEventPayload { - /** - * The context object passed with the raised intent. - */ - context: Context; - /** - * The intent that was raised. - */ - intent: string; - /** - * Details of the application instance that raised the intent. - */ - originatingApp?: AppIdentifier; - /** - * The requestUuid value of the raiseIntentRequest that the intentEvent being sent relates - * to. - */ - raiseIntentRequestUuid: string; -} +export type OpenErrorResponsePayload = + | 'MalformedContext' + | 'AppNotFound' + | 'AppTimeout' + | 'DesktopAgentNotFound' + | 'ErrorOnLaunch' + | 'ResolverUnavailable' + | 'AgentDisconnected' + | 'NotConnectedToBridge' + | 'ResponseToBridgeTimedOut' + | 'MalformedMessage'; /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -2903,11 +2932,11 @@ export interface IntentEventPayload { */ /** - * A request to unsubscribe a context listener. + * A request to add an event listener to a specific PrivateChannel. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface IntentListenerUnsubscribeRequest { +export interface PrivateChannelAddEventListenerRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2915,33 +2944,46 @@ export interface IntentListenerUnsubscribeRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: IntentListenerUnsubscribeRequestPayload; + payload: PrivateChannelAddEventListenerRequestPayload; /** * 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. */ - type: 'intentListenerUnsubscribeRequest'; + type: 'privateChannelAddEventListenerRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface IntentListenerUnsubscribeRequestPayload { - listenerUUID: string; +export interface PrivateChannelAddEventListenerRequestPayload { + /** + * The type of PrivateChannel event that the listener should be applied to, or null for all + * event types. + */ + listenerType: PrivateChannelEventType | null; + /** + * The Id of the PrivateChannel that the listener should be added to. + */ + privateChannelId: string; } +/** + * Type defining valid type strings for Private Channel events. + */ +export type PrivateChannelEventType = 'addContextListener' | 'unsubscribe' | 'disconnect'; + /** * 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. */ /** - * A response to a intentListenerUnsubscribe request. + * A response to a privateChannelAddEventListener request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface IntentListenerUnsubscribeResponse { +export interface PrivateChannelAddEventListenerResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -2951,12 +2993,22 @@ export interface IntentListenerUnsubscribeResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: BroadcastResponseResponsePayload; + payload: PrivateChannelAddEventListenerResponsePayload; /** * 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. */ - type: 'intentListenerUnsubscribeResponse'; + type: 'privateChannelAddEventListenerResponse'; +} + +/** + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. + */ +export interface PrivateChannelAddEventListenerResponsePayload { + error?: PurpleError; + listenerUUID?: string; } /** @@ -2965,13 +3017,12 @@ export interface IntentListenerUnsubscribeResponse { */ /** - * A request to deliver a result for an intent (which may include a `void` result that just - * indicates that the handler has run, returning no result). The result is tied to the - * intentEvent it relates to by quoting the `eventUuid` of the intentEvent in its payload. + * Request that indicates that a participant will no longer interact with a specified + * `PrivateChannel`. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface IntentResultRequest { +export interface PrivateChannelDisconnectRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -2979,61 +3030,102 @@ export interface IntentResultRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: IntentResultRequestPayload; + payload: PrivateChannelDisconnectRequestPayload; /** * 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. */ - type: 'intentResultRequest'; + type: 'privateChannelDisconnectRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface IntentResultRequestPayload { - /** - * The eventUuid value of the intentEvent that the result being sent relates to. - */ - intentEventUuid: string; - intentResult: IntentResult; +export interface PrivateChannelDisconnectRequestPayload { /** - * The requestUuid value of the raiseIntentRequest that the result being sent relates to. + * The Id of the Channel that should be disconnected from */ - raiseIntentRequestUuid: string; + channelId: string; } -export interface IntentResult { - context?: Context; - channel?: Channel; +/** + * 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. + */ + +/** + * A response to a privateChannelDisconnect request. + * + * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the + * payload contains an `error` property, the request was unsuccessful. + */ +export interface PrivateChannelDisconnectResponse { + /** + * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + */ + meta: AddContextListenerResponseMeta; + /** + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. + */ + payload: PrivateChannelDisconnectResponsePayload; + /** + * 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. + */ + type: 'privateChannelDisconnectResponse'; +} + +/** + * A payload for a response to an API call that will contain any return values or an `error` + * property containing a standardized error message indicating that the request was + * unsuccessful. + */ +export interface PrivateChannelDisconnectResponsePayload { + error?: PurpleError; } /** * 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. + * the message relates to, e.g. 'findIntent', with 'Response' appended. */ /** - * A response to a request to deliver an intent result. + * An event message from the Desktop Agent to an app indicating that another app has added a + * context listener to a specific PrivateChannel. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A message from a Desktop Agent to an FDC3-enabled app representing an event. */ -export interface IntentResultResponse { +export interface PrivateChannelOnAddContextListenerEvent { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. */ - meta: AddContextListenerResponseMeta; + meta: BroadcastEventMeta; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload contains details of the event that the app is being notified about. */ - payload: BroadcastResponseResponsePayload; + payload: PrivateChannelOnAddContextListenerEventPayload; /** * 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. */ - type: 'intentResultResponse'; + type: 'privateChannelOnAddContextListenerEvent'; +} + +/** + * The message payload contains details of the event that the app is being notified about. + */ +export interface PrivateChannelOnAddContextListenerEventPayload { + /** + * The type of the context listener added to the channel by another app, or null if it will + * listen to all types. + */ + contextType: null | string; + /** + * The Id of the PrivateChannel that the listener was added to. + */ + privateChannelId: string; } /** @@ -3042,76 +3134,77 @@ export interface IntentResultResponse { */ /** - * Request to join the app to the specified User channel. On successfully joining a channel, - * client code should make subsequent requests to get the current context of that channel - * for all registered context listeners and then call their handlers with it. + * An event message from the Desktop Agent to an app indicating that another app has + * disconnected from a specific PrivateChannel and will no longer interact with it. * - * A request message from an FDC3-enabled app to a Desktop Agent. + * A message from a Desktop Agent to an FDC3-enabled app representing an event. */ -export interface JoinUserChannelRequest { +export interface PrivateChannelOnDisconnectEvent { /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. */ - meta: AddContextListenerRequestMeta; + meta: BroadcastEventMeta; /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload contains details of the event that the app is being notified about. */ - payload: JoinUserChannelRequestPayload; + payload: PrivateChannelOnDisconnectEventPayload; /** * 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. + * the message relates to, e.g. 'findIntent', with 'Response' appended. */ - type: 'joinUserChannelRequest'; + type: 'privateChannelOnDisconnectEvent'; } /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload contains details of the event that the app is being notified about. */ -export interface JoinUserChannelRequestPayload { +export interface PrivateChannelOnDisconnectEventPayload { /** - * The id of the channel to join. + * The Id of the PrivateChannel that the app has disconnected from. */ - channelId: string; + privateChannelId: string; } /** * 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. + * the message relates to, e.g. 'findIntent', with 'Response' appended. */ /** - * A response to a joinUserChannel request. On receipt of this response, client code should - * make subsequent requests to get the current context of that channel for all registered - * context listeners and then call their handlers with it. + * An event message from the Desktop Agent to an app indicating that another app has + * unsubscribed a context listener from a specific PrivateChannel. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A message from a Desktop Agent to an FDC3-enabled app representing an event. */ -export interface JoinUserChannelResponse { +export interface PrivateChannelOnUnsubscribeEvent { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. */ - meta: AddContextListenerResponseMeta; + meta: BroadcastEventMeta; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload contains details of the event that the app is being notified about. */ - payload: JoinUserChannelResponsePayload; + payload: PrivateChannelOnUnsubscribeEventPayload; /** * 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. */ - type: 'joinUserChannelResponse'; + type: 'privateChannelOnUnsubscribeEvent'; } /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload contains details of the event that the app is being notified about. */ -export interface JoinUserChannelResponsePayload { - error?: PurpleError; +export interface PrivateChannelOnUnsubscribeEventPayload { + /** + * The type of the context listener unsubscribed from the channel by another app, or null if + * it was listening to all types. + */ + contextType: null | string; + /** + * The Id of the PrivateChannel that the listener was unsubscribed from. + */ + privateChannelId: string; } /** @@ -3120,11 +3213,11 @@ export interface JoinUserChannelResponsePayload { */ /** - * Request to remove the app from any User channel membership. + * A request to unsubscribe a context listener. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface LeaveCurrentChannelRequest { +export interface PrivateChannelUnsubscribeEventListenerRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -3132,18 +3225,20 @@ export interface LeaveCurrentChannelRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: LeaveCurrentChannelRequestPayload; + payload: PrivateChannelUnsubscribeEventListenerRequestPayload; /** * 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. */ - type: 'leaveCurrentChannelRequest'; + type: 'privateChannelUnsubscribeEventListenerRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface LeaveCurrentChannelRequestPayload {} +export interface PrivateChannelUnsubscribeEventListenerRequestPayload { + listenerUUID: string; +} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -3151,12 +3246,12 @@ export interface LeaveCurrentChannelRequestPayload {} */ /** - * A response to a leaveCurrentChannel request. + * A response to a privateChannelUnsubscribeEventListener request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface LeaveCurrentChannelResponse { +export interface PrivateChannelUnsubscribeEventListenerResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -3166,21 +3261,12 @@ export interface LeaveCurrentChannelResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: LeaveCurrentChannelResponsePayload; + payload: BroadcastResponseResponsePayload; /** * 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. */ - type: 'leaveCurrentChannelResponse'; -} - -/** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - */ -export interface LeaveCurrentChannelResponsePayload { - error?: PurpleError; + type: 'privateChannelUnsubscribeEventListenerResponse'; } /** @@ -3189,11 +3275,11 @@ export interface LeaveCurrentChannelResponsePayload { */ /** - * A request to open an application. + * A request to raise an unspecified intent for a specified context. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface OpenRequest { +export interface RaiseIntentForContextRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -3201,25 +3287,20 @@ export interface OpenRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: OpenRequestPayload; + payload: RaiseIntentForContextRequestPayload; /** * 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. */ - type: 'openRequest'; + type: 'raiseIntentForContextRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface OpenRequestPayload { - app: AppIdentifier; - /** - * If a Context object is passed in, this object will be provided to the opened application - * via a contextListener. The Context argument is functionally equivalent to opening the - * target app with no context and broadcasting the context directly to it. - */ - context?: Context; +export interface RaiseIntentForContextRequestPayload { + app?: AppIdentifier; + context: Context; } /** @@ -3228,12 +3309,12 @@ export interface OpenRequestPayload { */ /** - * A response to a open request. + * A response to a raiseIntentForContext request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface OpenResponse { +export interface RaiseIntentForContextResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -3242,44 +3323,90 @@ export interface OpenResponse { * A payload for a response to an API call that will contain any return values or an `error` * property containing a standardized error message indicating that the request was * unsuccessful. + * + * There are 3 possible responses to a raiseIntentForContext request, each of which sets a + * single property in the payload: Success (`intentResolution`), Needs further resolution + * (`appIntents`) or Error (`error`). */ - payload: OpenResponsePayload; + payload: RaiseIntentForContextResponsePayload; /** * 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. */ - type: 'openResponse'; + type: 'raiseIntentForContextResponse'; } /** * A payload for a response to an API call that will contain any return values or an `error` * property containing a standardized error message indicating that the request was * unsuccessful. + * + * There are 3 possible responses to a raiseIntentForContext request, each of which sets a + * single property in the payload: Success (`intentResolution`), Needs further resolution + * (`appIntents`) or Error (`error`). + * + * Response to a raiseIntentForContext request that needs additional resolution (i.e. show + * an intent resolver UI). + * + * Used if a raiseIntent request resulted in an error. */ -export interface OpenResponsePayload { - error?: OpenErrorResponsePayload; - appIdentifier?: AppIdentifier; +export interface RaiseIntentForContextResponsePayload { + /** + * Should be set if the raiseIntent request returned an error. + */ + error?: FindInstancesErrors; + /** + * Used if the raiseIntent request was successfully resolved. + */ + intentResolution?: IntentResolution; + /** + * Used if a raiseIntentForContext request requires additional resolution (e.g. by showing + * an intent resolver) before it can be handled. + */ + appIntents?: AppIntent[]; } /** - * Constants representing the errors that can be encountered when calling the `open` method - * on the DesktopAgent object (`fdc3`). + * Used if the raiseIntent request was successfully resolved. * - * Constants representing the errors that can be encountered when calling the `findIntent`, - * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the - * DesktopAgent (`fdc3`). + * IntentResolution provides a standard format for data returned upon resolving an intent. + * + * ```javascript + * //resolve a "Chain" type intent + * let resolution = await agent.raiseIntent("intentName", context); + * + * //resolve a "Client-Service" type intent with a data response or a Channel + * let resolution = await agent.raiseIntent("intentName", context); + * try { + * const result = await resolution.getResult(); + * if (result && result.broadcast) { + * console.log(`${resolution.source} returned a channel with id ${result.id}`); + * } else if (result){ + * console.log(`${resolution.source} returned data: ${JSON.stringify(result)}`); + * } else { + * console.error(`${resolution.source} didn't return data` + * } + * } catch(error) { + * console.error(`${resolution.source} returned an error: ${error}`); + * } + * + * // Use metadata about the resolving app instance to target a further intent + * await agent.raiseIntent("intentName", context, resolution.source); + * ``` */ -export type OpenErrorResponsePayload = - | 'MalformedContext' - | 'AppNotFound' - | 'AppTimeout' - | 'DesktopAgentNotFound' - | 'ErrorOnLaunch' - | 'ResolverUnavailable' - | 'AgentDisconnected' - | 'NotConnectedToBridge' - | 'ResponseToBridgeTimedOut' - | 'MalformedMessage'; +export interface IntentResolution { + /** + * The intent that was raised. May be used to determine which intent the user + * chose in response to `fdc3.raiseIntentForContext()`. + */ + intent: string; + /** + * Identifier for the app instance that was selected (or started) to resolve the intent. + * `source.instanceId` MUST be set, indicating the specific app instance that + * received the intent. + */ + source: AppIdentifier; +} /** * Identifies the type of the message and it is typically set to the FDC3 function name that @@ -3287,11 +3414,11 @@ export type OpenErrorResponsePayload = */ /** - * A request to add an event listener to a specific PrivateChannel. + * A request to raise an intent for a context. * * A request message from an FDC3-enabled app to a Desktop Agent. */ -export interface PrivateChannelAddEventListenerRequest { +export interface RaiseIntentRequest { /** * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. */ @@ -3299,46 +3426,35 @@ export interface PrivateChannelAddEventListenerRequest { /** * The message payload typically contains the arguments to FDC3 API functions. */ - payload: PrivateChannelAddEventListenerRequestPayload; + payload: RaiseIntentRequestPayload; /** * 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. */ - type: 'privateChannelAddEventListenerRequest'; + type: 'raiseIntentRequest'; } /** * The message payload typically contains the arguments to FDC3 API functions. */ -export interface PrivateChannelAddEventListenerRequestPayload { - /** - * The type of PrivateChannel event that the listener should be applied to, or null for all - * event types. - */ - listenerType: PrivateChannelEventType | null; - /** - * The Id of the PrivateChannel that the listener should be added to. - */ - privateChannelId: string; +export interface RaiseIntentRequestPayload { + app?: AppIdentifier; + context: Context; + intent: string; } -/** - * Type defining valid type strings for Private Channel events. - */ -export type PrivateChannelEventType = 'addContextListener' | 'unsubscribe' | 'disconnect'; - /** * 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. */ /** - * A response to a privateChannelAddEventListener request. + * A response to a raiseIntent request. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface PrivateChannelAddEventListenerResponse { +export interface RaiseIntentResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -3347,74 +3463,63 @@ export interface PrivateChannelAddEventListenerResponse { * A payload for a response to an API call that will contain any return values or an `error` * property containing a standardized error message indicating that the request was * unsuccessful. + * + * There are 3 possible responses to a raiseIntent request, each of which sets a single + * property in the payload: Success (`intentResolution`), Needs further resolution + * (`appIntent`) or Error (`error`). */ - payload: PrivateChannelAddEventListenerResponsePayload; + payload: RaiseIntentResponsePayload; /** * 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. */ - type: 'privateChannelAddEventListenerResponse'; + type: 'raiseIntentResponse'; } /** * A payload for a response to an API call that will contain any return values or an `error` * property containing a standardized error message indicating that the request was * unsuccessful. - */ -export interface PrivateChannelAddEventListenerResponsePayload { - error?: PurpleError; - listenerUUID?: string; -} - -/** - * 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. - */ - -/** - * Request that indicates that a participant will no longer interact with a specified - * `PrivateChannel`. * - * A request message from an FDC3-enabled app to a Desktop Agent. + * There are 3 possible responses to a raiseIntent request, each of which sets a single + * property in the payload: Success (`intentResolution`), Needs further resolution + * (`appIntent`) or Error (`error`). + * + * Response to a raiseIntent request that needs additional resolution (i.e. show an intent + * resolver UI). + * + * Used if a raiseIntent request resulted in an error. */ -export interface PrivateChannelDisconnectRequest { - /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. - */ - meta: AddContextListenerRequestMeta; +export interface RaiseIntentResponsePayload { /** - * The message payload typically contains the arguments to FDC3 API functions. + * Should be set if the raiseIntent request returned an error. */ - payload: PrivateChannelDisconnectRequestPayload; + error?: FindInstancesErrors; /** - * 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. + * Used if the raiseIntent request was successfully resolved. */ - type: 'privateChannelDisconnectRequest'; -} - -/** - * The message payload typically contains the arguments to FDC3 API functions. - */ -export interface PrivateChannelDisconnectRequestPayload { + intentResolution?: IntentResolution; /** - * The Id of the Channel that should be disconnected from + * Used if a raiseIntent request requires additional resolution (e.g. by showing an intent + * resolver) before it can be handled. */ - channelId: string; + appIntent?: AppIntent; } /** * 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. + * the message relates to, e.g. 'findIntent', with 'Response' appended. */ /** - * A response to a privateChannelDisconnect request. + * A secondary response to a request to raise an intent used to deliver the intent result. + * This message should quote the original requestUuid of the raiseIntentRequest message in + * its `meta.requestUuid` field. * * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the * payload contains an `error` property, the request was unsuccessful. */ -export interface PrivateChannelDisconnectResponse { +export interface RaiseIntentResultResponse { /** * Metadata for messages sent by a Desktop Agent to an app in response to an API call. */ @@ -3424,12 +3529,12 @@ export interface PrivateChannelDisconnectResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ - payload: PrivateChannelDisconnectResponsePayload; + payload: RaiseIntentResultResponsePayload; /** * 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. */ - type: 'privateChannelDisconnectResponse'; + type: 'raiseIntentResultResponse'; } /** @@ -3437,50 +3542,9 @@ export interface PrivateChannelDisconnectResponse { * property containing a standardized error message indicating that the request was * unsuccessful. */ -export interface PrivateChannelDisconnectResponsePayload { - error?: PurpleError; -} - -/** - * 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. - */ - -/** - * An event message from the Desktop Agent to an app indicating that another app has added a - * context listener to a specific PrivateChannel. - * - * A message from a Desktop Agent to an FDC3-enabled app representing an event. - */ -export interface PrivateChannelOnAddContextListenerEvent { - /** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. - */ - meta: BroadcastEventMeta; - /** - * The message payload contains details of the event that the app is being notified about. - */ - payload: PrivateChannelOnAddContextListenerEventPayload; - /** - * 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. - */ - type: 'privateChannelOnAddContextListenerEvent'; -} - -/** - * The message payload contains details of the event that the app is being notified about. - */ -export interface PrivateChannelOnAddContextListenerEventPayload { - /** - * The type of the context listener added to the channel by another app, or null if it will - * listen to all types. - */ - contextType: null | string; - /** - * The Id of the PrivateChannel that the listener was added to. - */ - privateChannelId: string; +export interface RaiseIntentResultResponsePayload { + error?: ResponsePayloadError; + intentResult?: IntentResult; } /** @@ -3489,501 +3553,363 @@ export interface PrivateChannelOnAddContextListenerEventPayload { */ /** - * An event message from the Desktop Agent to an app indicating that another app has - * disconnected from a specific PrivateChannel and will no longer interact with it. + * Hello message sent by an application to a parent window or frame when attempting to + * establish connectivity to a Desktop Agent. * - * A message from a Desktop Agent to an FDC3-enabled app representing an event. + * A message used during the connection flow for an application to a Desktop Agent in a + * browser window. Used for messages sent in either direction. */ -export interface PrivateChannelOnDisconnectEvent { +export interface WebConnectionProtocol1Hello { /** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. + * Metadata for a Web Connection Protocol message. */ - meta: BroadcastEventMeta; + meta: WebConnectionProtocol1HelloMeta; /** - * The message payload contains details of the event that the app is being notified about. + * The message payload, containing data pertaining to this connection step. */ - payload: PrivateChannelOnDisconnectEventPayload; + payload: WebConnectionProtocol1HelloPayload; /** - * 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. + * Identifies the type of the connection step message. */ - type: 'privateChannelOnDisconnectEvent'; + type: 'WCP1Hello'; } /** - * The message payload contains details of the event that the app is being notified about. + * Metadata for a Web Connection Protocol message. */ -export interface PrivateChannelOnDisconnectEventPayload { - /** - * The Id of the PrivateChannel that the app has disconnected from. - */ - privateChannelId: string; +export interface WebConnectionProtocol1HelloMeta { + connectionAttemptUuid: string; + timestamp: Date; } /** - * 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. - */ - -/** - * An event message from the Desktop Agent to an app indicating that another app has - * unsubscribed a context listener from a specific PrivateChannel. - * - * A message from a Desktop Agent to an FDC3-enabled app representing an event. + * The message payload, containing data pertaining to this connection step. */ -export interface PrivateChannelOnUnsubscribeEvent { +export interface WebConnectionProtocol1HelloPayload { /** - * Metadata for messages sent by a Desktop Agent to an app notifying it of an event. + * The current URL of the page attempting to connect. This may differ from the identityUrl, + * but the origins MUST match. */ - meta: BroadcastEventMeta; + actualUrl: string; /** - * The message payload contains details of the event that the app is being notified about. + * A flag that may be used to indicate that a channel selector user interface is or is not + * required. Set to `false` if the app includes its own interface for selecting channels or + * does not work with user channels. */ - payload: PrivateChannelOnUnsubscribeEventPayload; + channelSelector?: boolean; /** - * 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. + * The version of FDC3 API that the app supports. */ - type: 'privateChannelOnUnsubscribeEvent'; -} - -/** - * The message payload contains details of the event that the app is being notified about. - */ -export interface PrivateChannelOnUnsubscribeEventPayload { + fdc3Version: string; /** - * The type of the context listener unsubscribed from the channel by another app, or null if - * it was listening to all types. + * URL to use for the identity of the application. Desktop Agents MUST validate that the + * origin of the message matches the URL, but MAY implement custom comparison logic. */ - contextType: null | string; + identityUrl: string; /** - * The Id of the PrivateChannel that the listener was unsubscribed from. + * A flag that may be used to indicate that an intent resolver is or is not required. Set to + * `false` if no intents, or only targeted intents, are raised. */ - privateChannelId: string; + intentResolver?: boolean; + [property: string]: any; } /** - * 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. + * Identifies the type of the connection step message. */ /** - * A request to unsubscribe a context listener. + * Response from a Desktop Agent to an application requesting access to it indicating that + * it should load a specified URL into a hidden iframe in order to establish connectivity to + * a Desktop Agent. * - * A request message from an FDC3-enabled app to a Desktop Agent. + * A message used during the connection flow for an application to a Desktop Agent in a + * browser window. Used for messages sent in either direction. */ -export interface PrivateChannelUnsubscribeEventListenerRequest { +export interface WebConnectionProtocol2LoadURL { /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + * Metadata for a Web Connection Protocol message. */ - meta: AddContextListenerRequestMeta; + meta: WebConnectionProtocol1HelloMeta; /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload, containing data pertaining to this connection step. */ - payload: PrivateChannelUnsubscribeEventListenerRequestPayload; + payload: WebConnectionProtocol2LoadURLPayload; /** - * 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. + * Identifies the type of the connection step message. */ - type: 'privateChannelUnsubscribeEventListenerRequest'; + type: 'WCP2LoadUrl'; } /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload, containing data pertaining to this connection step. */ -export interface PrivateChannelUnsubscribeEventListenerRequestPayload { - listenerUUID: string; +export interface WebConnectionProtocol2LoadURLPayload { + /** + * A URL which can be used to establish communication with the Desktop Agent, via loading + * the URL into an iframe and restarting the Web Connection protocol with the iframe as the + * target. + */ + iframeUrl: string; + [property: string]: any; } /** - * 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. + * Identifies the type of the connection step message. */ /** - * A response to a privateChannelUnsubscribeEventListener request. + * Handshake message sent by the Desktop Agent to the app (with a MessagePort appended) that + * should be used for subsequent communication steps. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A message used during the connection flow for an application to a Desktop Agent in a + * browser window. Used for messages sent in either direction. */ -export interface PrivateChannelUnsubscribeEventListenerResponse { +export interface WebConnectionProtocol3Handshake { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * Metadata for a Web Connection Protocol message. */ - meta: AddContextListenerResponseMeta; + meta: WebConnectionProtocol1HelloMeta; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload, containing data pertaining to this connection step. */ - payload: BroadcastResponseResponsePayload; + payload: WebConnectionProtocol3HandshakePayload; /** - * 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. + * Identifies the type of the connection step message. */ - type: 'privateChannelUnsubscribeEventListenerResponse'; + type: 'WCP3Handshake'; } /** - * 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. - */ - -/** - * A request to raise an unspecified intent for a specified context. - * - * A request message from an FDC3-enabled app to a Desktop Agent. + * The message payload, containing data pertaining to this connection step. */ -export interface RaiseIntentForContextRequest { +export interface WebConnectionProtocol3HandshakePayload { /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + * Indicates whether a channel selector user interface is required and the URL to use to do + * so. Set to `true` to use the default or `false` to disable the channel selector (as the + * Desktop Agent will handle it another way). */ - meta: AddContextListenerRequestMeta; + channelSelectorUrl: boolean | string; /** - * The message payload typically contains the arguments to FDC3 API functions. + * The version of FDC3 API that the Desktop Agent will provide support for. */ - payload: RaiseIntentForContextRequestPayload; + fdc3Version: string; /** - * 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. + * Indicates whether an intent resolver user interface is required and the URL to use to do + * so. Set to `true` to use the default or `false` to disable the intent resolver (as the + * Desktop Agent will handle it another way). */ - type: 'raiseIntentForContextRequest'; -} - -/** - * The message payload typically contains the arguments to FDC3 API functions. - */ -export interface RaiseIntentForContextRequestPayload { - app?: AppIdentifier; - context: Context; + intentResolverUrl: boolean | string; } /** - * 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. + * Identifies the type of the connection step message. */ /** - * A response to a raiseIntentForContext request. + * Identity Validation request from an app attempting to connect to a Desktop Agent. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A message used during the connection flow for an application to a Desktop Agent in a + * browser window. Used for messages sent in either direction. */ -export interface RaiseIntentForContextResponse { +export interface WebConnectionProtocol4ValidateAppIdentity { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * Metadata for a Web Connection Protocol message. */ - meta: AddContextListenerResponseMeta; + meta: WebConnectionProtocol1HelloMeta; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - * - * There are 3 possible responses to a raiseIntentForContext request, each of which sets a - * single property in the payload: Success (`intentResolution`), Needs further resolution - * (`appIntents`) or Error (`error`). + * The message payload, containing data pertaining to this connection step. */ - payload: RaiseIntentForContextResponsePayload; + payload: WebConnectionProtocol4ValidateAppIdentityPayload; /** - * 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. + * Identifies the type of the connection step message. */ - type: 'raiseIntentForContextResponse'; + type: 'WCP4ValidateAppIdentity'; } /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - * - * There are 3 possible responses to a raiseIntentForContext request, each of which sets a - * single property in the payload: Success (`intentResolution`), Needs further resolution - * (`appIntents`) or Error (`error`). - * - * Response to a raiseIntentForContext request that needs additional resolution (i.e. show - * an intent resolver UI). - * - * Used if a raiseIntent request resulted in an error. + * The message payload, containing data pertaining to this connection step. */ -export interface RaiseIntentForContextResponsePayload { - /** - * Should be set if the raiseIntent request returned an error. - */ - error?: FindInstancesErrors; +export interface WebConnectionProtocol4ValidateAppIdentityPayload { /** - * Used if the raiseIntent request was successfully resolved. + * The current URL of the page attempting to connect. This may differ from the identityUrl, + * but the origins MUST match. */ - intentResolution?: IntentResolution; + actualUrl: string; /** - * Used if a raiseIntentForContext request requires additional resolution (e.g. by showing - * an intent resolver) before it can be handled. + * URL to use for the identity of the application. Desktop Agents MUST validate that the + * origin of the message matches the URL, but MAY implement custom comparison logic. */ - appIntents?: AppIntent[]; -} - -/** - * Used if the raiseIntent request was successfully resolved. - * - * IntentResolution provides a standard format for data returned upon resolving an intent. - * - * ```javascript - * //resolve a "Chain" type intent - * let resolution = await agent.raiseIntent("intentName", context); - * - * //resolve a "Client-Service" type intent with a data response or a Channel - * let resolution = await agent.raiseIntent("intentName", context); - * try { - * const result = await resolution.getResult(); - * if (result && result.broadcast) { - * console.log(`${resolution.source} returned a channel with id ${result.id}`); - * } else if (result){ - * console.log(`${resolution.source} returned data: ${JSON.stringify(result)}`); - * } else { - * console.error(`${resolution.source} didn't return data` - * } - * } catch(error) { - * console.error(`${resolution.source} returned an error: ${error}`); - * } - * - * // Use metadata about the resolving app instance to target a further intent - * await agent.raiseIntent("intentName", context, resolution.source); - * ``` - */ -export interface IntentResolution { + identityUrl: string; /** - * The intent that was raised. May be used to determine which intent the user - * chose in response to `fdc3.raiseIntentForContext()`. + * If an application has previously connected to the Desktop Agent, it may specify its prior + * instance id and associated instance UUID to request the same same instance Id be assigned. */ - intent: string; + instanceId?: string; /** - * Identifier for the app instance that was selected (or started) to resolve the intent. - * `source.instanceId` MUST be set, indicating the specific app instance that - * received the intent. + * Instance UUID associated with the requested instanceId. */ - source: AppIdentifier; + instanceUuid?: string; } /** - * 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. + * Identifies the type of the connection step message. */ /** - * A request to raise an intent for a context. + * Message sent by the Desktop Agent to an app if their identity validation fails. * - * A request message from an FDC3-enabled app to a Desktop Agent. + * A message used during the connection flow for an application to a Desktop Agent in a + * browser window. Used for messages sent in either direction. */ -export interface RaiseIntentRequest { +export interface WebConnectionProtocol5ValidateAppIdentityFailedResponse { /** - * Metadata for a request message sent by an FDC3-enabled app to a Desktop Agent. + * Metadata for a Web Connection Protocol message. */ - meta: AddContextListenerRequestMeta; + meta: WebConnectionProtocol1HelloMeta; /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload, containing data pertaining to this connection step. */ - payload: RaiseIntentRequestPayload; + payload: WebConnectionProtocol5ValidateAppIdentityFailedResponsePayload; /** - * 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. + * Identifies the type of the connection step message. */ - type: 'raiseIntentRequest'; + type: 'WCP5ValidateAppIdentityFailedResponse'; } /** - * The message payload typically contains the arguments to FDC3 API functions. + * The message payload, containing data pertaining to this connection step. */ -export interface RaiseIntentRequestPayload { - app?: AppIdentifier; - context: Context; - intent: string; +export interface WebConnectionProtocol5ValidateAppIdentityFailedResponsePayload { + message?: string; } /** - * 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. + * Identifies the type of the connection step message. */ /** - * A response to a raiseIntent request. + * Message sent by the Desktop Agent to an app after successful identity validation. * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * A message used during the connection flow for an application to a Desktop Agent in a + * browser window. Used for messages sent in either direction. */ -export interface RaiseIntentResponse { +export interface WebConnectionProtocol5ValidateAppIdentitySuccessResponse { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * Metadata for a Web Connection Protocol message. */ - meta: AddContextListenerResponseMeta; + meta: WebConnectionProtocol1HelloMeta; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - * - * There are 3 possible responses to a raiseIntent request, each of which sets a single - * property in the payload: Success (`intentResolution`), Needs further resolution - * (`appIntent`) or Error (`error`). + * The message payload, containing data pertaining to this connection step. */ - payload: RaiseIntentResponsePayload; + payload: WebConnectionProtocol5ValidateAppIdentitySuccessResponsePayload; /** - * 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. + * Identifies the type of the connection step message. */ - type: 'raiseIntentResponse'; + type: 'WCP5ValidateAppIdentityResponse'; +} + +/** + * The message payload, containing data pertaining to this connection step. + */ +export interface WebConnectionProtocol5ValidateAppIdentitySuccessResponsePayload { + /** + * The appId that the app's identity was validated against. + */ + appId: string; + /** + * Implementation metadata for the Desktop Agent, which includes an appMetadata element + * containing a copy of the app's own metadata. + */ + implementationMetadata: ImplementationMetadata; + /** + * The instance Id granted to the application by the Desktop Agent. + */ + instanceId: string; + /** + * Instance UUID associated with the instanceId granted, which may be used to retrieve the + * same instanceId if the app is reloaded or navigates. + */ + instanceUuid: string; } /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. - * - * There are 3 possible responses to a raiseIntent request, each of which sets a single - * property in the payload: Success (`intentResolution`), Needs further resolution - * (`appIntent`) or Error (`error`). - * - * Response to a raiseIntent request that needs additional resolution (i.e. show an intent - * resolver UI). + * Identifies the type of the connection step message. + */ + +/** + * Goodbye message to be sent to the Desktop Agent when disconnecting (e.g. when closing the + * window or navigating). Desktop Agents should close the MessagePort after receiving this + * message, but retain instance details in case the application reconnects (e.g. after a + * navigation event). * - * Used if a raiseIntent request resulted in an error. + * A message used during the connection flow for an application to a Desktop Agent in a + * browser window. Used for messages sent in either direction. */ -export interface RaiseIntentResponsePayload { - /** - * Should be set if the raiseIntent request returned an error. - */ - error?: FindInstancesErrors; +export interface WebConnectionProtocol6Goodbye { /** - * Used if the raiseIntent request was successfully resolved. + * Metadata for a Web Connection Protocol message. */ - intentResolution?: IntentResolution; + meta: WebConnectionProtocol6GoodbyeMeta; /** - * Used if a raiseIntent request requires additional resolution (e.g. by showing an intent - * resolver) before it can be handled. + * Identifies the type of the connection step message. */ - appIntent?: AppIntent; + type: 'WCP6Goodbye'; } /** - * 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. + * Metadata for a Web Connection Protocol message. */ +export interface WebConnectionProtocol6GoodbyeMeta { + timestamp: Date; +} /** - * A secondary response to a request to raise an intent used to deliver the intent result. - * This message should quote the original requestUuid of the raiseIntentRequest message in - * its `meta.requestUuid` field. - * - * A message from a Desktop Agent to an FDC3-enabled app responding to an API call. If the - * payload contains an `error` property, the request was unsuccessful. + * Identifies the type of the connection step message. */ -export interface RaiseIntentResultResponse { + +/** + * A message used during the connection flow for an application to a Desktop Agent in a + * browser window. Used for messages sent in either direction. + */ +export interface WebConnectionProtocolMessage { /** - * Metadata for messages sent by a Desktop Agent to an app in response to an API call. + * Metadata for a Web Connection Protocol message. */ - meta: AddContextListenerResponseMeta; + meta: ConnectionStepMetadata; /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * The message payload, containing data pertaining to this connection step. */ - payload: RaiseIntentResultResponsePayload; + payload?: { [key: string]: any }; /** - * 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. + * Identifies the type of the connection step message. */ - type: 'raiseIntentResultResponse'; + type: ConnectionStepMessageType; } /** - * A payload for a response to an API call that will contain any return values or an `error` - * property containing a standardized error message indicating that the request was - * unsuccessful. + * Metadata for a Web Connection Protocol message. */ -export interface RaiseIntentResultResponsePayload { - error?: ResponsePayloadError; - intentResult?: IntentResult; +export interface ConnectionStepMetadata { + timestamp: Date; + connectionAttemptUuid?: string; } /** - * 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. + * Identifies the type of the connection step message. */ +export type ConnectionStepMessageType = + | 'WCP1Hello' + | 'WCP2LoadUrl' + | 'WCP3Handshake' + | 'WCP4ValidateAppIdentity' + | 'WCP5ValidateAppIdentityFailedResponse' + | 'WCP5ValidateAppIdentityResponse' + | 'WCP6Goodbye'; // Converts JSON strings to/from your types // and asserts the results of JSON.parse at runtime export class Convert { - public static toWebConnectionProtocol1Hello(json: string): WebConnectionProtocol1Hello { - return cast(JSON.parse(json), r('WebConnectionProtocol1Hello')); - } - - public static webConnectionProtocol1HelloToJson(value: WebConnectionProtocol1Hello): string { - return JSON.stringify(uncast(value, r('WebConnectionProtocol1Hello')), null, 2); - } - - public static toWebConnectionProtocol2LoadURL(json: string): WebConnectionProtocol2LoadURL { - return cast(JSON.parse(json), r('WebConnectionProtocol2LoadURL')); - } - - public static webConnectionProtocol2LoadURLToJson(value: WebConnectionProtocol2LoadURL): string { - return JSON.stringify(uncast(value, r('WebConnectionProtocol2LoadURL')), null, 2); - } - - public static toWebConnectionProtocol3Handshake(json: string): WebConnectionProtocol3Handshake { - return cast(JSON.parse(json), r('WebConnectionProtocol3Handshake')); - } - - public static webConnectionProtocol3HandshakeToJson(value: WebConnectionProtocol3Handshake): string { - return JSON.stringify(uncast(value, r('WebConnectionProtocol3Handshake')), null, 2); - } - - public static toWebConnectionProtocol4ValidateAppIdentity(json: string): WebConnectionProtocol4ValidateAppIdentity { - return cast(JSON.parse(json), r('WebConnectionProtocol4ValidateAppIdentity')); - } - - public static webConnectionProtocol4ValidateAppIdentityToJson( - value: WebConnectionProtocol4ValidateAppIdentity - ): string { - return JSON.stringify(uncast(value, r('WebConnectionProtocol4ValidateAppIdentity')), null, 2); - } - - public static toWebConnectionProtocol5ValidateAppIdentityFailedResponse( - json: string - ): WebConnectionProtocol5ValidateAppIdentityFailedResponse { - return cast(JSON.parse(json), r('WebConnectionProtocol5ValidateAppIdentityFailedResponse')); - } - - public static webConnectionProtocol5ValidateAppIdentityFailedResponseToJson( - value: WebConnectionProtocol5ValidateAppIdentityFailedResponse - ): string { - return JSON.stringify(uncast(value, r('WebConnectionProtocol5ValidateAppIdentityFailedResponse')), null, 2); - } - - public static toWebConnectionProtocol5ValidateAppIdentitySuccessResponse( - json: string - ): WebConnectionProtocol5ValidateAppIdentitySuccessResponse { - return cast(JSON.parse(json), r('WebConnectionProtocol5ValidateAppIdentitySuccessResponse')); - } - - public static webConnectionProtocol5ValidateAppIdentitySuccessResponseToJson( - value: WebConnectionProtocol5ValidateAppIdentitySuccessResponse - ): string { - return JSON.stringify(uncast(value, r('WebConnectionProtocol5ValidateAppIdentitySuccessResponse')), null, 2); - } - - public static toWebConnectionProtocol6Goodbye(json: string): WebConnectionProtocol6Goodbye { - return cast(JSON.parse(json), r('WebConnectionProtocol6Goodbye')); - } - - public static webConnectionProtocol6GoodbyeToJson(value: WebConnectionProtocol6Goodbye): string { - return JSON.stringify(uncast(value, r('WebConnectionProtocol6Goodbye')), null, 2); - } - - public static toWebConnectionProtocolMessage(json: string): WebConnectionProtocolMessage { - return cast(JSON.parse(json), r('WebConnectionProtocolMessage')); - } - - public static webConnectionProtocolMessageToJson(value: WebConnectionProtocolMessage): string { - return JSON.stringify(uncast(value, r('WebConnectionProtocolMessage')), null, 2); - } - public static toAddContextListenerRequest(json: string): AddContextListenerRequest { return cast(JSON.parse(json), r('AddContextListenerRequest')); } @@ -4136,14 +4062,6 @@ export class Convert { return JSON.stringify(uncast(value, r('EventListenerUnsubscribeResponse')), null, 2); } - public static toFdc3UserInterfaceChannelSelected(json: string): Fdc3UserInterfaceChannelSelected { - return cast(JSON.parse(json), r('Fdc3UserInterfaceChannelSelected')); - } - - public static fdc3UserInterfaceChannelSelectedToJson(value: Fdc3UserInterfaceChannelSelected): string { - return JSON.stringify(uncast(value, r('Fdc3UserInterfaceChannelSelected')), null, 2); - } - public static toFdc3UserInterfaceChannels(json: string): Fdc3UserInterfaceChannels { return cast(JSON.parse(json), r('Fdc3UserInterfaceChannels')); } @@ -4152,6 +4070,14 @@ export class Convert { return JSON.stringify(uncast(value, r('Fdc3UserInterfaceChannels')), null, 2); } + public static toFdc3UserInterfaceChannelSelected(json: string): Fdc3UserInterfaceChannelSelected { + return cast(JSON.parse(json), r('Fdc3UserInterfaceChannelSelected')); + } + + public static fdc3UserInterfaceChannelSelectedToJson(value: Fdc3UserInterfaceChannelSelected): string { + return JSON.stringify(uncast(value, r('Fdc3UserInterfaceChannelSelected')), null, 2); + } + public static toFdc3UserInterfaceDrag(json: string): Fdc3UserInterfaceDrag { return cast(JSON.parse(json), r('Fdc3UserInterfaceDrag')); } @@ -4564,16 +4490,90 @@ export class Convert { return cast(JSON.parse(json), r('RaiseIntentResponse')); } - public static raiseIntentResponseToJson(value: RaiseIntentResponse): string { - return JSON.stringify(uncast(value, r('RaiseIntentResponse')), null, 2); + public static raiseIntentResponseToJson(value: RaiseIntentResponse): string { + return JSON.stringify(uncast(value, r('RaiseIntentResponse')), null, 2); + } + + public static toRaiseIntentResultResponse(json: string): RaiseIntentResultResponse { + return cast(JSON.parse(json), r('RaiseIntentResultResponse')); + } + + public static raiseIntentResultResponseToJson(value: RaiseIntentResultResponse): string { + return JSON.stringify(uncast(value, r('RaiseIntentResultResponse')), null, 2); + } + + public static toWebConnectionProtocol1Hello(json: string): WebConnectionProtocol1Hello { + return cast(JSON.parse(json), r('WebConnectionProtocol1Hello')); + } + + public static webConnectionProtocol1HelloToJson(value: WebConnectionProtocol1Hello): string { + return JSON.stringify(uncast(value, r('WebConnectionProtocol1Hello')), null, 2); + } + + public static toWebConnectionProtocol2LoadURL(json: string): WebConnectionProtocol2LoadURL { + return cast(JSON.parse(json), r('WebConnectionProtocol2LoadURL')); + } + + public static webConnectionProtocol2LoadURLToJson(value: WebConnectionProtocol2LoadURL): string { + return JSON.stringify(uncast(value, r('WebConnectionProtocol2LoadURL')), null, 2); + } + + public static toWebConnectionProtocol3Handshake(json: string): WebConnectionProtocol3Handshake { + return cast(JSON.parse(json), r('WebConnectionProtocol3Handshake')); + } + + public static webConnectionProtocol3HandshakeToJson(value: WebConnectionProtocol3Handshake): string { + return JSON.stringify(uncast(value, r('WebConnectionProtocol3Handshake')), null, 2); + } + + public static toWebConnectionProtocol4ValidateAppIdentity(json: string): WebConnectionProtocol4ValidateAppIdentity { + return cast(JSON.parse(json), r('WebConnectionProtocol4ValidateAppIdentity')); + } + + public static webConnectionProtocol4ValidateAppIdentityToJson( + value: WebConnectionProtocol4ValidateAppIdentity + ): string { + return JSON.stringify(uncast(value, r('WebConnectionProtocol4ValidateAppIdentity')), null, 2); + } + + public static toWebConnectionProtocol5ValidateAppIdentityFailedResponse( + json: string + ): WebConnectionProtocol5ValidateAppIdentityFailedResponse { + return cast(JSON.parse(json), r('WebConnectionProtocol5ValidateAppIdentityFailedResponse')); + } + + public static webConnectionProtocol5ValidateAppIdentityFailedResponseToJson( + value: WebConnectionProtocol5ValidateAppIdentityFailedResponse + ): string { + return JSON.stringify(uncast(value, r('WebConnectionProtocol5ValidateAppIdentityFailedResponse')), null, 2); + } + + public static toWebConnectionProtocol5ValidateAppIdentitySuccessResponse( + json: string + ): WebConnectionProtocol5ValidateAppIdentitySuccessResponse { + return cast(JSON.parse(json), r('WebConnectionProtocol5ValidateAppIdentitySuccessResponse')); + } + + public static webConnectionProtocol5ValidateAppIdentitySuccessResponseToJson( + value: WebConnectionProtocol5ValidateAppIdentitySuccessResponse + ): string { + return JSON.stringify(uncast(value, r('WebConnectionProtocol5ValidateAppIdentitySuccessResponse')), null, 2); + } + + public static toWebConnectionProtocol6Goodbye(json: string): WebConnectionProtocol6Goodbye { + return cast(JSON.parse(json), r('WebConnectionProtocol6Goodbye')); + } + + public static webConnectionProtocol6GoodbyeToJson(value: WebConnectionProtocol6Goodbye): string { + return JSON.stringify(uncast(value, r('WebConnectionProtocol6Goodbye')), null, 2); } - public static toRaiseIntentResultResponse(json: string): RaiseIntentResultResponse { - return cast(JSON.parse(json), r('RaiseIntentResultResponse')); + public static toWebConnectionProtocolMessage(json: string): WebConnectionProtocolMessage { + return cast(JSON.parse(json), r('WebConnectionProtocolMessage')); } - public static raiseIntentResultResponseToJson(value: RaiseIntentResultResponse): string { - return JSON.stringify(uncast(value, r('RaiseIntentResultResponse')), null, 2); + public static webConnectionProtocolMessageToJson(value: WebConnectionProtocolMessage): string { + return JSON.stringify(uncast(value, r('WebConnectionProtocolMessage')), null, 2); } } @@ -4671,250 +4671,79 @@ function transform(val: any, typ: any, getProps: any, key: any = '', parent: any if (val === null || typeof val !== 'object' || Array.isArray(val)) { return invalidValue(l(ref || 'object'), val, key, parent); } - const result: any = {}; - Object.getOwnPropertyNames(props).forEach(key => { - const prop = props[key]; - const v = Object.prototype.hasOwnProperty.call(val, key) ? val[key] : undefined; - result[prop.key] = transform(v, prop.typ, getProps, key, ref); - }); - Object.getOwnPropertyNames(val).forEach(key => { - if (!Object.prototype.hasOwnProperty.call(props, key)) { - result[key] = transform(val[key], additional, getProps, key, ref); - } - }); - return result; - } - - if (typ === 'any') return val; - if (typ === null) { - if (val === null) return val; - return invalidValue(typ, val, key, parent); - } - if (typ === false) return invalidValue(typ, val, key, parent); - let ref: any = undefined; - while (typeof typ === 'object' && typ.ref !== undefined) { - ref = typ.ref; - typ = typeMap[typ.ref]; - } - if (Array.isArray(typ)) return transformEnum(typ, val); - if (typeof typ === 'object') { - return typ.hasOwnProperty('unionMembers') - ? transformUnion(typ.unionMembers, val) - : typ.hasOwnProperty('arrayItems') - ? transformArray(typ.arrayItems, val) - : typ.hasOwnProperty('props') - ? transformObject(getProps(typ), typ.additional, val) - : invalidValue(typ, val, key, parent); - } - // Numbers can be parsed by Date but shouldn't be. - if (typ === Date && typeof val !== 'number') return transformDate(val); - return transformPrimitive(typ, val); -} - -function cast(val: any, typ: any): T { - return transform(val, typ, jsonToJSProps); -} - -function uncast(val: T, typ: any): any { - return transform(val, typ, jsToJSONProps); -} - -function l(typ: any) { - return { literal: typ }; -} - -function a(typ: any) { - return { arrayItems: typ }; -} - -function u(...typs: any[]) { - return { unionMembers: typs }; -} - -function o(props: any[], additional: any) { - return { props, additional }; -} - -function m(additional: any) { - return { props: [], additional }; -} - -function r(name: string) { - return { ref: name }; -} - -const typeMap: any = { - WebConnectionProtocol1Hello: o( - [ - { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, - { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol1HelloPayload') }, - { json: 'type', js: 'type', typ: r('WebConnectionProtocol1HelloType') }, - ], - false - ), - WebConnectionProtocol1HelloMeta: o( - [ - { json: 'connectionAttemptUuid', js: 'connectionAttemptUuid', typ: '' }, - { json: 'timestamp', js: 'timestamp', typ: Date }, - ], - false - ), - WebConnectionProtocol1HelloPayload: o( - [ - { json: 'actualUrl', js: 'actualUrl', typ: '' }, - { json: 'channelSelector', js: 'channelSelector', typ: u(undefined, true) }, - { json: 'fdc3Version', js: 'fdc3Version', typ: '' }, - { json: 'identityUrl', js: 'identityUrl', typ: '' }, - { json: 'intentResolver', js: 'intentResolver', typ: u(undefined, true) }, - ], - 'any' - ), - WebConnectionProtocol2LoadURL: o( - [ - { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, - { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol2LoadURLPayload') }, - { json: 'type', js: 'type', typ: r('WebConnectionProtocol2LoadURLType') }, - ], - false - ), - WebConnectionProtocol2LoadURLPayload: o([{ json: 'iframeUrl', js: 'iframeUrl', typ: '' }], 'any'), - WebConnectionProtocol3Handshake: o( - [ - { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, - { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol3HandshakePayload') }, - { json: 'type', js: 'type', typ: r('WebConnectionProtocol3HandshakeType') }, - ], - false - ), - WebConnectionProtocol3HandshakePayload: o( - [ - { json: 'channelSelectorUrl', js: 'channelSelectorUrl', typ: u(true, '') }, - { json: 'fdc3Version', js: 'fdc3Version', typ: '' }, - { json: 'intentResolverUrl', js: 'intentResolverUrl', typ: u(true, '') }, - ], - false - ), - WebConnectionProtocol4ValidateAppIdentity: o( - [ - { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, - { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol4ValidateAppIdentityPayload') }, - { json: 'type', js: 'type', typ: r('WebConnectionProtocol4ValidateAppIdentityType') }, - ], - false - ), - WebConnectionProtocol4ValidateAppIdentityPayload: o( - [ - { json: 'actualUrl', js: 'actualUrl', typ: '' }, - { json: 'identityUrl', js: 'identityUrl', typ: '' }, - { json: 'instanceId', js: 'instanceId', typ: u(undefined, '') }, - { json: 'instanceUuid', js: 'instanceUuid', typ: u(undefined, '') }, - ], - false - ), - WebConnectionProtocol5ValidateAppIdentityFailedResponse: o( - [ - { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, - { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol5ValidateAppIdentityFailedResponsePayload') }, - { json: 'type', js: 'type', typ: r('WebConnectionProtocol5ValidateAppIdentityFailedResponseType') }, - ], - false - ), - WebConnectionProtocol5ValidateAppIdentityFailedResponsePayload: o( - [{ json: 'message', js: 'message', typ: u(undefined, '') }], - false - ), - WebConnectionProtocol5ValidateAppIdentitySuccessResponse: o( - [ - { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, - { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol5ValidateAppIdentitySuccessResponsePayload') }, - { json: 'type', js: 'type', typ: r('WebConnectionProtocol5ValidateAppIdentitySuccessResponseType') }, - ], - false - ), - WebConnectionProtocol5ValidateAppIdentitySuccessResponsePayload: o( - [ - { json: 'appId', js: 'appId', typ: '' }, - { json: 'implementationMetadata', js: 'implementationMetadata', typ: r('ImplementationMetadata') }, - { json: 'instanceId', js: 'instanceId', typ: '' }, - { json: 'instanceUuid', js: 'instanceUuid', typ: '' }, - ], - false - ), - ImplementationMetadata: o( - [ - { json: 'appMetadata', js: 'appMetadata', typ: r('AppMetadata') }, - { json: 'fdc3Version', js: 'fdc3Version', typ: '' }, - { json: 'optionalFeatures', js: 'optionalFeatures', typ: r('OptionalFeatures') }, - { json: 'provider', js: 'provider', typ: '' }, - { json: 'providerVersion', js: 'providerVersion', typ: u(undefined, '') }, - ], - false - ), - AppMetadata: o( - [ - { json: 'appId', js: 'appId', typ: '' }, - { json: 'description', js: 'description', typ: u(undefined, '') }, - { json: 'desktopAgent', js: 'desktopAgent', typ: u(undefined, '') }, - { json: 'icons', js: 'icons', typ: u(undefined, a(r('Icon'))) }, - { json: 'instanceId', js: 'instanceId', typ: u(undefined, '') }, - { json: 'instanceMetadata', js: 'instanceMetadata', typ: u(undefined, m('any')) }, - { json: 'name', js: 'name', typ: u(undefined, '') }, - { json: 'resultType', js: 'resultType', typ: u(undefined, u(null, '')) }, - { json: 'screenshots', js: 'screenshots', typ: u(undefined, a(r('Image'))) }, - { json: 'title', js: 'title', typ: u(undefined, '') }, - { json: 'tooltip', js: 'tooltip', typ: u(undefined, '') }, - { json: 'version', js: 'version', typ: u(undefined, '') }, - ], - false - ), - Icon: o( - [ - { json: 'size', js: 'size', typ: u(undefined, '') }, - { json: 'src', js: 'src', typ: '' }, - { json: 'type', js: 'type', typ: u(undefined, '') }, - ], - false - ), - Image: o( - [ - { json: 'label', js: 'label', typ: u(undefined, '') }, - { json: 'size', js: 'size', typ: u(undefined, '') }, - { json: 'src', js: 'src', typ: '' }, - { json: 'type', js: 'type', typ: u(undefined, '') }, - ], - false - ), - OptionalFeatures: o( - [ - { json: 'DesktopAgentBridging', js: 'DesktopAgentBridging', typ: true }, - { json: 'OriginatingAppMetadata', js: 'OriginatingAppMetadata', typ: true }, - { json: 'UserChannelMembershipAPIs', js: 'UserChannelMembershipAPIs', typ: true }, - ], - false - ), - WebConnectionProtocol6Goodbye: o( - [ - { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol6GoodbyeMeta') }, - { json: 'type', js: 'type', typ: r('WebConnectionProtocol6GoodbyeType') }, - ], - false - ), - WebConnectionProtocol6GoodbyeMeta: o([{ json: 'timestamp', js: 'timestamp', typ: Date }], false), - WebConnectionProtocolMessage: o( - [ - { json: 'meta', js: 'meta', typ: r('ConnectionStepMetadata') }, - { json: 'payload', js: 'payload', typ: u(undefined, m('any')) }, - { json: 'type', js: 'type', typ: r('ConnectionStepMessageType') }, - ], - false - ), - ConnectionStepMetadata: o( - [ - { json: 'timestamp', js: 'timestamp', typ: Date }, - { json: 'connectionAttemptUuid', js: 'connectionAttemptUuid', typ: u(undefined, '') }, - ], - false - ), + const result: any = {}; + Object.getOwnPropertyNames(props).forEach(key => { + const prop = props[key]; + const v = Object.prototype.hasOwnProperty.call(val, key) ? val[key] : undefined; + result[prop.key] = transform(v, prop.typ, getProps, key, ref); + }); + Object.getOwnPropertyNames(val).forEach(key => { + if (!Object.prototype.hasOwnProperty.call(props, key)) { + result[key] = transform(val[key], additional, getProps, key, ref); + } + }); + return result; + } + + if (typ === 'any') return val; + if (typ === null) { + if (val === null) return val; + return invalidValue(typ, val, key, parent); + } + if (typ === false) return invalidValue(typ, val, key, parent); + let ref: any = undefined; + while (typeof typ === 'object' && typ.ref !== undefined) { + ref = typ.ref; + typ = typeMap[typ.ref]; + } + if (Array.isArray(typ)) return transformEnum(typ, val); + if (typeof typ === 'object') { + return typ.hasOwnProperty('unionMembers') + ? transformUnion(typ.unionMembers, val) + : typ.hasOwnProperty('arrayItems') + ? transformArray(typ.arrayItems, val) + : typ.hasOwnProperty('props') + ? transformObject(getProps(typ), typ.additional, val) + : invalidValue(typ, val, key, parent); + } + // Numbers can be parsed by Date but shouldn't be. + if (typ === Date && typeof val !== 'number') return transformDate(val); + return transformPrimitive(typ, val); +} + +function cast(val: any, typ: any): T { + return transform(val, typ, jsonToJSProps); +} + +function uncast(val: T, typ: any): any { + return transform(val, typ, jsToJSONProps); +} + +function l(typ: any) { + return { literal: typ }; +} + +function a(typ: any) { + return { arrayItems: typ }; +} + +function u(...typs: any[]) { + return { unionMembers: typs }; +} + +function o(props: any[], additional: any) { + return { props, additional }; +} + +function m(additional: any) { + return { props: [], additional }; +} + +function r(name: string) { + return { ref: name }; +} + +const typeMap: any = { AddContextListenerRequest: o( [ { json: 'meta', js: 'meta', typ: r('AddContextListenerRequestMeta') }, @@ -5211,14 +5040,6 @@ const typeMap: any = { ], false ), - Fdc3UserInterfaceChannelSelected: o( - [ - { json: 'payload', js: 'payload', typ: r('Fdc3UserInterfaceChannelSelectedPayload') }, - { json: 'type', js: 'type', typ: r('Fdc3UserInterfaceChannelSelectedType') }, - ], - false - ), - Fdc3UserInterfaceChannelSelectedPayload: o([{ json: 'selected', js: 'selected', typ: u(null, '') }], false), Fdc3UserInterfaceChannels: o( [ { json: 'payload', js: 'payload', typ: r('Fdc3UserInterfaceChannelsPayload') }, @@ -5233,6 +5054,14 @@ const typeMap: any = { ], false ), + Fdc3UserInterfaceChannelSelected: o( + [ + { json: 'payload', js: 'payload', typ: r('Fdc3UserInterfaceChannelSelectedPayload') }, + { json: 'type', js: 'type', typ: r('Fdc3UserInterfaceChannelSelectedType') }, + ], + false + ), + Fdc3UserInterfaceChannelSelectedPayload: o([{ json: 'selected', js: 'selected', typ: u(null, '') }], false), Fdc3UserInterfaceDrag: o( [ { json: 'payload', js: 'payload', typ: r('Fdc3UserInterfaceDragPayload') }, @@ -5313,6 +5142,40 @@ const typeMap: any = { ], false ), + AppMetadata: o( + [ + { json: 'appId', js: 'appId', typ: '' }, + { json: 'description', js: 'description', typ: u(undefined, '') }, + { json: 'desktopAgent', js: 'desktopAgent', typ: u(undefined, '') }, + { json: 'icons', js: 'icons', typ: u(undefined, a(r('Icon'))) }, + { json: 'instanceId', js: 'instanceId', typ: u(undefined, '') }, + { json: 'instanceMetadata', js: 'instanceMetadata', typ: u(undefined, m('any')) }, + { json: 'name', js: 'name', typ: u(undefined, '') }, + { json: 'resultType', js: 'resultType', typ: u(undefined, u(null, '')) }, + { json: 'screenshots', js: 'screenshots', typ: u(undefined, a(r('Image'))) }, + { json: 'title', js: 'title', typ: u(undefined, '') }, + { json: 'tooltip', js: 'tooltip', typ: u(undefined, '') }, + { json: 'version', js: 'version', typ: u(undefined, '') }, + ], + false + ), + Icon: o( + [ + { json: 'size', js: 'size', typ: u(undefined, '') }, + { json: 'src', js: 'src', typ: '' }, + { json: 'type', js: 'type', typ: u(undefined, '') }, + ], + false + ), + Image: o( + [ + { json: 'label', js: 'label', typ: u(undefined, '') }, + { json: 'size', js: 'size', typ: u(undefined, '') }, + { json: 'src', js: 'src', typ: '' }, + { json: 'type', js: 'type', typ: u(undefined, '') }, + ], + false + ), IntentMetadata: o( [ { json: 'displayName', js: 'displayName', typ: u(undefined, '') }, @@ -5545,6 +5408,24 @@ const typeMap: any = { ], false ), + ImplementationMetadata: o( + [ + { json: 'appMetadata', js: 'appMetadata', typ: r('AppMetadata') }, + { json: 'fdc3Version', js: 'fdc3Version', typ: '' }, + { json: 'optionalFeatures', js: 'optionalFeatures', typ: r('OptionalFeatures') }, + { json: 'provider', js: 'provider', typ: '' }, + { json: 'providerVersion', js: 'providerVersion', typ: u(undefined, '') }, + ], + false + ), + OptionalFeatures: o( + [ + { json: 'DesktopAgentBridging', js: 'DesktopAgentBridging', typ: true }, + { json: 'OriginatingAppMetadata', js: 'OriginatingAppMetadata', typ: true }, + { json: 'UserChannelMembershipAPIs', js: 'UserChannelMembershipAPIs', typ: true }, + ], + false + ), GetOrCreateChannelRequest: o( [ { json: 'meta', js: 'meta', typ: r('AddContextListenerRequestMeta') }, @@ -5922,37 +5803,140 @@ const typeMap: any = { ], false ), - RaiseIntentResultResponse: o( + RaiseIntentResultResponse: o( + [ + { json: 'meta', js: 'meta', typ: r('AddContextListenerResponseMeta') }, + { json: 'payload', js: 'payload', typ: r('RaiseIntentResultResponsePayload') }, + { json: 'type', js: 'type', typ: r('RaiseIntentResultResponseType') }, + ], + false + ), + RaiseIntentResultResponsePayload: o( + [ + { json: 'error', js: 'error', typ: u(undefined, r('ResponsePayloadError')) }, + { json: 'intentResult', js: 'intentResult', typ: u(undefined, r('IntentResult')) }, + ], + false + ), + WebConnectionProtocol1Hello: o( + [ + { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, + { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol1HelloPayload') }, + { json: 'type', js: 'type', typ: r('WebConnectionProtocol1HelloType') }, + ], + false + ), + WebConnectionProtocol1HelloMeta: o( + [ + { json: 'connectionAttemptUuid', js: 'connectionAttemptUuid', typ: '' }, + { json: 'timestamp', js: 'timestamp', typ: Date }, + ], + false + ), + WebConnectionProtocol1HelloPayload: o( + [ + { json: 'actualUrl', js: 'actualUrl', typ: '' }, + { json: 'channelSelector', js: 'channelSelector', typ: u(undefined, true) }, + { json: 'fdc3Version', js: 'fdc3Version', typ: '' }, + { json: 'identityUrl', js: 'identityUrl', typ: '' }, + { json: 'intentResolver', js: 'intentResolver', typ: u(undefined, true) }, + ], + 'any' + ), + WebConnectionProtocol2LoadURL: o( + [ + { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, + { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol2LoadURLPayload') }, + { json: 'type', js: 'type', typ: r('WebConnectionProtocol2LoadURLType') }, + ], + false + ), + WebConnectionProtocol2LoadURLPayload: o([{ json: 'iframeUrl', js: 'iframeUrl', typ: '' }], 'any'), + WebConnectionProtocol3Handshake: o( + [ + { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, + { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol3HandshakePayload') }, + { json: 'type', js: 'type', typ: r('WebConnectionProtocol3HandshakeType') }, + ], + false + ), + WebConnectionProtocol3HandshakePayload: o( + [ + { json: 'channelSelectorUrl', js: 'channelSelectorUrl', typ: u(true, '') }, + { json: 'fdc3Version', js: 'fdc3Version', typ: '' }, + { json: 'intentResolverUrl', js: 'intentResolverUrl', typ: u(true, '') }, + ], + false + ), + WebConnectionProtocol4ValidateAppIdentity: o( + [ + { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, + { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol4ValidateAppIdentityPayload') }, + { json: 'type', js: 'type', typ: r('WebConnectionProtocol4ValidateAppIdentityType') }, + ], + false + ), + WebConnectionProtocol4ValidateAppIdentityPayload: o( + [ + { json: 'actualUrl', js: 'actualUrl', typ: '' }, + { json: 'identityUrl', js: 'identityUrl', typ: '' }, + { json: 'instanceId', js: 'instanceId', typ: u(undefined, '') }, + { json: 'instanceUuid', js: 'instanceUuid', typ: u(undefined, '') }, + ], + false + ), + WebConnectionProtocol5ValidateAppIdentityFailedResponse: o( + [ + { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, + { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol5ValidateAppIdentityFailedResponsePayload') }, + { json: 'type', js: 'type', typ: r('WebConnectionProtocol5ValidateAppIdentityFailedResponseType') }, + ], + false + ), + WebConnectionProtocol5ValidateAppIdentityFailedResponsePayload: o( + [{ json: 'message', js: 'message', typ: u(undefined, '') }], + false + ), + WebConnectionProtocol5ValidateAppIdentitySuccessResponse: o( + [ + { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol1HelloMeta') }, + { json: 'payload', js: 'payload', typ: r('WebConnectionProtocol5ValidateAppIdentitySuccessResponsePayload') }, + { json: 'type', js: 'type', typ: r('WebConnectionProtocol5ValidateAppIdentitySuccessResponseType') }, + ], + false + ), + WebConnectionProtocol5ValidateAppIdentitySuccessResponsePayload: o( + [ + { json: 'appId', js: 'appId', typ: '' }, + { json: 'implementationMetadata', js: 'implementationMetadata', typ: r('ImplementationMetadata') }, + { json: 'instanceId', js: 'instanceId', typ: '' }, + { json: 'instanceUuid', js: 'instanceUuid', typ: '' }, + ], + false + ), + WebConnectionProtocol6Goodbye: o( + [ + { json: 'meta', js: 'meta', typ: r('WebConnectionProtocol6GoodbyeMeta') }, + { json: 'type', js: 'type', typ: r('WebConnectionProtocol6GoodbyeType') }, + ], + false + ), + WebConnectionProtocol6GoodbyeMeta: o([{ json: 'timestamp', js: 'timestamp', typ: Date }], false), + WebConnectionProtocolMessage: o( [ - { json: 'meta', js: 'meta', typ: r('AddContextListenerResponseMeta') }, - { json: 'payload', js: 'payload', typ: r('RaiseIntentResultResponsePayload') }, - { json: 'type', js: 'type', typ: r('RaiseIntentResultResponseType') }, + { json: 'meta', js: 'meta', typ: r('ConnectionStepMetadata') }, + { json: 'payload', js: 'payload', typ: u(undefined, m('any')) }, + { json: 'type', js: 'type', typ: r('ConnectionStepMessageType') }, ], false ), - RaiseIntentResultResponsePayload: o( + ConnectionStepMetadata: o( [ - { json: 'error', js: 'error', typ: u(undefined, r('ResponsePayloadError')) }, - { json: 'intentResult', js: 'intentResult', typ: u(undefined, r('IntentResult')) }, + { json: 'timestamp', js: 'timestamp', typ: Date }, + { json: 'connectionAttemptUuid', js: 'connectionAttemptUuid', typ: u(undefined, '') }, ], false ), - WebConnectionProtocol1HelloType: ['WCP1Hello'], - WebConnectionProtocol2LoadURLType: ['WCP2LoadUrl'], - WebConnectionProtocol3HandshakeType: ['WCP3Handshake'], - WebConnectionProtocol4ValidateAppIdentityType: ['WCP4ValidateAppIdentity'], - WebConnectionProtocol5ValidateAppIdentityFailedResponseType: ['WCP5ValidateAppIdentityFailedResponse'], - WebConnectionProtocol5ValidateAppIdentitySuccessResponseType: ['WCP5ValidateAppIdentityResponse'], - WebConnectionProtocol6GoodbyeType: ['WCP6Goodbye'], - ConnectionStepMessageType: [ - 'WCP1Hello', - 'WCP2LoadUrl', - 'WCP3Handshake', - 'WCP4ValidateAppIdentity', - 'WCP5ValidateAppIdentityFailedResponse', - 'WCP5ValidateAppIdentityResponse', - 'WCP6Goodbye', - ], AddContextListenerRequestType: ['addContextListenerRequest'], PurpleError: ['AccessDenied', 'CreationFailed', 'MalformedContext', 'NoChannelFound'], AddContextListenerResponseType: ['addContextListenerResponse'], @@ -6074,8 +6058,8 @@ const typeMap: any = { CreatePrivateChannelResponseType: ['createPrivateChannelResponse'], EventListenerUnsubscribeRequestType: ['eventListenerUnsubscribeRequest'], EventListenerUnsubscribeResponseType: ['eventListenerUnsubscribeResponse'], - Fdc3UserInterfaceChannelSelectedType: ['Fdc3UserInterfaceChannelSelected'], Fdc3UserInterfaceChannelsType: ['Fdc3UserInterfaceChannels'], + Fdc3UserInterfaceChannelSelectedType: ['Fdc3UserInterfaceChannelSelected'], Fdc3UserInterfaceDragType: ['Fdc3UserInterfaceDrag'], Fdc3UserInterfaceHandshakeType: ['Fdc3UserInterfaceHandshake'], Fdc3UserInterfaceHelloType: ['Fdc3UserInterfaceHello'], @@ -6166,6 +6150,22 @@ const typeMap: any = { RaiseIntentRequestType: ['raiseIntentRequest'], RaiseIntentResponseType: ['raiseIntentResponse'], RaiseIntentResultResponseType: ['raiseIntentResultResponse'], + WebConnectionProtocol1HelloType: ['WCP1Hello'], + WebConnectionProtocol2LoadURLType: ['WCP2LoadUrl'], + WebConnectionProtocol3HandshakeType: ['WCP3Handshake'], + WebConnectionProtocol4ValidateAppIdentityType: ['WCP4ValidateAppIdentity'], + WebConnectionProtocol5ValidateAppIdentityFailedResponseType: ['WCP5ValidateAppIdentityFailedResponse'], + WebConnectionProtocol5ValidateAppIdentitySuccessResponseType: ['WCP5ValidateAppIdentityResponse'], + WebConnectionProtocol6GoodbyeType: ['WCP6Goodbye'], + ConnectionStepMessageType: [ + 'WCP1Hello', + 'WCP2LoadUrl', + 'WCP3Handshake', + 'WCP4ValidateAppIdentity', + 'WCP5ValidateAppIdentityFailedResponse', + 'WCP5ValidateAppIdentityResponse', + 'WCP6Goodbye', + ], }; export type AppRequestMessage = @@ -6191,224 +6191,49 @@ export type AppRequestMessage = | JoinUserChannelRequest | LeaveCurrentChannelRequest | OpenRequest - | PrivateChannelAddEventListenerRequest - | PrivateChannelDisconnectRequest - | PrivateChannelUnsubscribeEventListenerRequest - | RaiseIntentForContextRequest - | RaiseIntentRequest; - -export type AgentResponseMessage = - | AddContextListenerResponse - | AddEventListenerResponse - | AddIntentListenerResponse - | BroadcastResponse - | ContextListenerUnsubscribeResponse - | CreatePrivateChannelResponse - | EventListenerUnsubscribeResponse - | FindInstancesResponse - | FindIntentResponse - | FindIntentsByContextResponse - | GetAppMetadataResponse - | GetCurrentChannelResponse - | GetCurrentContextResponse - | GetInfoResponse - | GetOrCreateChannelResponse - | GetUserChannelsResponse - | IntentListenerUnsubscribeResponse - | IntentResultResponse - | JoinUserChannelResponse - | LeaveCurrentChannelResponse - | OpenResponse - | PrivateChannelAddEventListenerResponse - | PrivateChannelDisconnectResponse - | PrivateChannelUnsubscribeEventListenerResponse - | RaiseIntentForContextResponse - | RaiseIntentResponse - | RaiseIntentResultResponse; - -export type AgentEventMessage = - | BroadcastEvent - | ChannelChangedEvent - | HeartbeatEvent - | IntentEvent - | PrivateChannelOnAddContextListenerEvent - | PrivateChannelOnDisconnectEvent - | PrivateChannelOnUnsubscribeEvent; - -/** - * Returns true if the value has a type property with value 'WCP1Hello'. This is a fast check that does not check the format of the message - */ -export function isWebConnectionProtocol1Hello(value: any): value is WebConnectionProtocol1Hello { - return value != null && value.type === 'WCP1Hello'; -} - -/** - * Returns true if value is a valid WebConnectionProtocol1Hello. This checks the type against the json schema for the message and will be slower - */ -export function isValidWebConnectionProtocol1Hello(value: any): value is WebConnectionProtocol1Hello { - try { - Convert.webConnectionProtocol1HelloToJson(value); - return true; - } catch (_e: any) { - return false; - } -} - -export const WEB_CONNECTION_PROTOCOL1_HELLO_TYPE = 'WebConnectionProtocol1Hello'; - -/** - * Returns true if the value has a type property with value 'WCP2LoadUrl'. This is a fast check that does not check the format of the message - */ -export function isWebConnectionProtocol2LoadURL(value: any): value is WebConnectionProtocol2LoadURL { - return value != null && value.type === 'WCP2LoadUrl'; -} - -/** - * Returns true if value is a valid WebConnectionProtocol2LoadURL. This checks the type against the json schema for the message and will be slower - */ -export function isValidWebConnectionProtocol2LoadURL(value: any): value is WebConnectionProtocol2LoadURL { - try { - Convert.webConnectionProtocol2LoadURLToJson(value); - return true; - } catch (_e: any) { - return false; - } -} - -export const WEB_CONNECTION_PROTOCOL2_LOAD_U_R_L_TYPE = 'WebConnectionProtocol2LoadURL'; - -/** - * Returns true if the value has a type property with value 'WCP3Handshake'. This is a fast check that does not check the format of the message - */ -export function isWebConnectionProtocol3Handshake(value: any): value is WebConnectionProtocol3Handshake { - return value != null && value.type === 'WCP3Handshake'; -} - -/** - * Returns true if value is a valid WebConnectionProtocol3Handshake. This checks the type against the json schema for the message and will be slower - */ -export function isValidWebConnectionProtocol3Handshake(value: any): value is WebConnectionProtocol3Handshake { - try { - Convert.webConnectionProtocol3HandshakeToJson(value); - return true; - } catch (_e: any) { - return false; - } -} - -export const WEB_CONNECTION_PROTOCOL3_HANDSHAKE_TYPE = 'WebConnectionProtocol3Handshake'; - -/** - * Returns true if the value has a type property with value 'WCP4ValidateAppIdentity'. This is a fast check that does not check the format of the message - */ -export function isWebConnectionProtocol4ValidateAppIdentity( - value: any -): value is WebConnectionProtocol4ValidateAppIdentity { - return value != null && value.type === 'WCP4ValidateAppIdentity'; -} - -/** - * Returns true if value is a valid WebConnectionProtocol4ValidateAppIdentity. This checks the type against the json schema for the message and will be slower - */ -export function isValidWebConnectionProtocol4ValidateAppIdentity( - value: any -): value is WebConnectionProtocol4ValidateAppIdentity { - try { - Convert.webConnectionProtocol4ValidateAppIdentityToJson(value); - return true; - } catch (_e: any) { - return false; - } -} - -export const WEB_CONNECTION_PROTOCOL4_VALIDATE_APP_IDENTITY_TYPE = 'WebConnectionProtocol4ValidateAppIdentity'; - -/** - * Returns true if the value has a type property with value 'WCP5ValidateAppIdentityFailedResponse'. This is a fast check that does not check the format of the message - */ -export function isWebConnectionProtocol5ValidateAppIdentityFailedResponse( - value: any -): value is WebConnectionProtocol5ValidateAppIdentityFailedResponse { - return value != null && value.type === 'WCP5ValidateAppIdentityFailedResponse'; -} - -/** - * Returns true if value is a valid WebConnectionProtocol5ValidateAppIdentityFailedResponse. This checks the type against the json schema for the message and will be slower - */ -export function isValidWebConnectionProtocol5ValidateAppIdentityFailedResponse( - value: any -): value is WebConnectionProtocol5ValidateAppIdentityFailedResponse { - try { - Convert.webConnectionProtocol5ValidateAppIdentityFailedResponseToJson(value); - return true; - } catch (_e: any) { - return false; - } -} - -export const WEB_CONNECTION_PROTOCOL5_VALIDATE_APP_IDENTITY_FAILED_RESPONSE_TYPE = - 'WebConnectionProtocol5ValidateAppIdentityFailedResponse'; - -/** - * Returns true if the value has a type property with value 'WCP5ValidateAppIdentityResponse'. This is a fast check that does not check the format of the message - */ -export function isWebConnectionProtocol5ValidateAppIdentitySuccessResponse( - value: any -): value is WebConnectionProtocol5ValidateAppIdentitySuccessResponse { - return value != null && value.type === 'WCP5ValidateAppIdentityResponse'; -} - -/** - * Returns true if value is a valid WebConnectionProtocol5ValidateAppIdentitySuccessResponse. This checks the type against the json schema for the message and will be slower - */ -export function isValidWebConnectionProtocol5ValidateAppIdentitySuccessResponse( - value: any -): value is WebConnectionProtocol5ValidateAppIdentitySuccessResponse { - try { - Convert.webConnectionProtocol5ValidateAppIdentitySuccessResponseToJson(value); - return true; - } catch (_e: any) { - return false; - } -} - -export const WEB_CONNECTION_PROTOCOL5_VALIDATE_APP_IDENTITY_SUCCESS_RESPONSE_TYPE = - 'WebConnectionProtocol5ValidateAppIdentitySuccessResponse'; - -/** - * Returns true if the value has a type property with value 'WCP6Goodbye'. This is a fast check that does not check the format of the message - */ -export function isWebConnectionProtocol6Goodbye(value: any): value is WebConnectionProtocol6Goodbye { - return value != null && value.type === 'WCP6Goodbye'; -} - -/** - * Returns true if value is a valid WebConnectionProtocol6Goodbye. This checks the type against the json schema for the message and will be slower - */ -export function isValidWebConnectionProtocol6Goodbye(value: any): value is WebConnectionProtocol6Goodbye { - try { - Convert.webConnectionProtocol6GoodbyeToJson(value); - return true; - } catch (_e: any) { - return false; - } -} - -export const WEB_CONNECTION_PROTOCOL6_GOODBYE_TYPE = 'WebConnectionProtocol6Goodbye'; + | PrivateChannelAddEventListenerRequest + | PrivateChannelDisconnectRequest + | PrivateChannelUnsubscribeEventListenerRequest + | RaiseIntentForContextRequest + | RaiseIntentRequest; -/** - * Returns true if value is a valid WebConnectionProtocolMessage. This checks the type against the json schema for the message and will be slower - */ -export function isValidWebConnectionProtocolMessage(value: any): value is WebConnectionProtocolMessage { - try { - Convert.webConnectionProtocolMessageToJson(value); - return true; - } catch (_e: any) { - return false; - } -} +export type AgentResponseMessage = + | AddContextListenerResponse + | AddEventListenerResponse + | AddIntentListenerResponse + | BroadcastResponse + | ContextListenerUnsubscribeResponse + | CreatePrivateChannelResponse + | EventListenerUnsubscribeResponse + | FindInstancesResponse + | FindIntentResponse + | FindIntentsByContextResponse + | GetAppMetadataResponse + | GetCurrentChannelResponse + | GetCurrentContextResponse + | GetInfoResponse + | GetOrCreateChannelResponse + | GetUserChannelsResponse + | IntentListenerUnsubscribeResponse + | IntentResultResponse + | JoinUserChannelResponse + | LeaveCurrentChannelResponse + | OpenResponse + | PrivateChannelAddEventListenerResponse + | PrivateChannelDisconnectResponse + | PrivateChannelUnsubscribeEventListenerResponse + | RaiseIntentForContextResponse + | RaiseIntentResponse + | RaiseIntentResultResponse; -export const WEB_CONNECTION_PROTOCOL_MESSAGE_TYPE = 'WebConnectionProtocolMessage'; +export type AgentEventMessage = + | BroadcastEvent + | ChannelChangedEvent + | HeartbeatEvent + | IntentEvent + | PrivateChannelOnAddContextListenerEvent + | PrivateChannelOnDisconnectEvent + | PrivateChannelOnUnsubscribeEvent; /** * Returns true if the value has a type property with value 'addContextListenerRequest'. This is a fast check that does not check the format of the message @@ -6747,46 +6572,46 @@ export function isValidEventListenerUnsubscribeResponse(value: any): value is Ev export const EVENT_LISTENER_UNSUBSCRIBE_RESPONSE_TYPE = 'EventListenerUnsubscribeResponse'; /** - * Returns true if the value has a type property with value 'Fdc3UserInterfaceChannelSelected'. This is a fast check that does not check the format of the message + * Returns true if the value has a type property with value 'Fdc3UserInterfaceChannels'. This is a fast check that does not check the format of the message */ -export function isFdc3UserInterfaceChannelSelected(value: any): value is Fdc3UserInterfaceChannelSelected { - return value != null && value.type === 'Fdc3UserInterfaceChannelSelected'; +export function isFdc3UserInterfaceChannels(value: any): value is Fdc3UserInterfaceChannels { + return value != null && value.type === 'Fdc3UserInterfaceChannels'; } /** - * Returns true if value is a valid Fdc3UserInterfaceChannelSelected. This checks the type against the json schema for the message and will be slower + * Returns true if value is a valid Fdc3UserInterfaceChannels. This checks the type against the json schema for the message and will be slower */ -export function isValidFdc3UserInterfaceChannelSelected(value: any): value is Fdc3UserInterfaceChannelSelected { +export function isValidFdc3UserInterfaceChannels(value: any): value is Fdc3UserInterfaceChannels { try { - Convert.fdc3UserInterfaceChannelSelectedToJson(value); + Convert.fdc3UserInterfaceChannelsToJson(value); return true; } catch (_e: any) { return false; } } -export const FDC3_USER_INTERFACE_CHANNEL_SELECTED_TYPE = 'Fdc3UserInterfaceChannelSelected'; +export const FDC3_USER_INTERFACE_CHANNELS_TYPE = 'Fdc3UserInterfaceChannels'; /** - * Returns true if the value has a type property with value 'Fdc3UserInterfaceChannels'. This is a fast check that does not check the format of the message + * Returns true if the value has a type property with value 'Fdc3UserInterfaceChannelSelected'. This is a fast check that does not check the format of the message */ -export function isFdc3UserInterfaceChannels(value: any): value is Fdc3UserInterfaceChannels { - return value != null && value.type === 'Fdc3UserInterfaceChannels'; +export function isFdc3UserInterfaceChannelSelected(value: any): value is Fdc3UserInterfaceChannelSelected { + return value != null && value.type === 'Fdc3UserInterfaceChannelSelected'; } /** - * Returns true if value is a valid Fdc3UserInterfaceChannels. This checks the type against the json schema for the message and will be slower + * Returns true if value is a valid Fdc3UserInterfaceChannelSelected. This checks the type against the json schema for the message and will be slower */ -export function isValidFdc3UserInterfaceChannels(value: any): value is Fdc3UserInterfaceChannels { +export function isValidFdc3UserInterfaceChannelSelected(value: any): value is Fdc3UserInterfaceChannelSelected { try { - Convert.fdc3UserInterfaceChannelsToJson(value); + Convert.fdc3UserInterfaceChannelSelectedToJson(value); return true; } catch (_e: any) { return false; } } -export const FDC3_USER_INTERFACE_CHANNELS_TYPE = 'Fdc3UserInterfaceChannels'; +export const FDC3_USER_INTERFACE_CHANNEL_SELECTED_TYPE = 'Fdc3UserInterfaceChannelSelected'; /** * Returns true if the value has a type property with value 'Fdc3UserInterfaceDrag'. This is a fast check that does not check the format of the message @@ -7889,3 +7714,178 @@ export function isValidRaiseIntentResultResponse(value: any): value is RaiseInte } export const RAISE_INTENT_RESULT_RESPONSE_TYPE = 'RaiseIntentResultResponse'; + +/** + * Returns true if the value has a type property with value 'WCP1Hello'. This is a fast check that does not check the format of the message + */ +export function isWebConnectionProtocol1Hello(value: any): value is WebConnectionProtocol1Hello { + return value != null && value.type === 'WCP1Hello'; +} + +/** + * Returns true if value is a valid WebConnectionProtocol1Hello. This checks the type against the json schema for the message and will be slower + */ +export function isValidWebConnectionProtocol1Hello(value: any): value is WebConnectionProtocol1Hello { + try { + Convert.webConnectionProtocol1HelloToJson(value); + return true; + } catch (_e: any) { + return false; + } +} + +export const WEB_CONNECTION_PROTOCOL1_HELLO_TYPE = 'WebConnectionProtocol1Hello'; + +/** + * Returns true if the value has a type property with value 'WCP2LoadUrl'. This is a fast check that does not check the format of the message + */ +export function isWebConnectionProtocol2LoadURL(value: any): value is WebConnectionProtocol2LoadURL { + return value != null && value.type === 'WCP2LoadUrl'; +} + +/** + * Returns true if value is a valid WebConnectionProtocol2LoadURL. This checks the type against the json schema for the message and will be slower + */ +export function isValidWebConnectionProtocol2LoadURL(value: any): value is WebConnectionProtocol2LoadURL { + try { + Convert.webConnectionProtocol2LoadURLToJson(value); + return true; + } catch (_e: any) { + return false; + } +} + +export const WEB_CONNECTION_PROTOCOL2_LOAD_U_R_L_TYPE = 'WebConnectionProtocol2LoadURL'; + +/** + * Returns true if the value has a type property with value 'WCP3Handshake'. This is a fast check that does not check the format of the message + */ +export function isWebConnectionProtocol3Handshake(value: any): value is WebConnectionProtocol3Handshake { + return value != null && value.type === 'WCP3Handshake'; +} + +/** + * Returns true if value is a valid WebConnectionProtocol3Handshake. This checks the type against the json schema for the message and will be slower + */ +export function isValidWebConnectionProtocol3Handshake(value: any): value is WebConnectionProtocol3Handshake { + try { + Convert.webConnectionProtocol3HandshakeToJson(value); + return true; + } catch (_e: any) { + return false; + } +} + +export const WEB_CONNECTION_PROTOCOL3_HANDSHAKE_TYPE = 'WebConnectionProtocol3Handshake'; + +/** + * Returns true if the value has a type property with value 'WCP4ValidateAppIdentity'. This is a fast check that does not check the format of the message + */ +export function isWebConnectionProtocol4ValidateAppIdentity( + value: any +): value is WebConnectionProtocol4ValidateAppIdentity { + return value != null && value.type === 'WCP4ValidateAppIdentity'; +} + +/** + * Returns true if value is a valid WebConnectionProtocol4ValidateAppIdentity. This checks the type against the json schema for the message and will be slower + */ +export function isValidWebConnectionProtocol4ValidateAppIdentity( + value: any +): value is WebConnectionProtocol4ValidateAppIdentity { + try { + Convert.webConnectionProtocol4ValidateAppIdentityToJson(value); + return true; + } catch (_e: any) { + return false; + } +} + +export const WEB_CONNECTION_PROTOCOL4_VALIDATE_APP_IDENTITY_TYPE = 'WebConnectionProtocol4ValidateAppIdentity'; + +/** + * Returns true if the value has a type property with value 'WCP5ValidateAppIdentityFailedResponse'. This is a fast check that does not check the format of the message + */ +export function isWebConnectionProtocol5ValidateAppIdentityFailedResponse( + value: any +): value is WebConnectionProtocol5ValidateAppIdentityFailedResponse { + return value != null && value.type === 'WCP5ValidateAppIdentityFailedResponse'; +} + +/** + * Returns true if value is a valid WebConnectionProtocol5ValidateAppIdentityFailedResponse. This checks the type against the json schema for the message and will be slower + */ +export function isValidWebConnectionProtocol5ValidateAppIdentityFailedResponse( + value: any +): value is WebConnectionProtocol5ValidateAppIdentityFailedResponse { + try { + Convert.webConnectionProtocol5ValidateAppIdentityFailedResponseToJson(value); + return true; + } catch (_e: any) { + return false; + } +} + +export const WEB_CONNECTION_PROTOCOL5_VALIDATE_APP_IDENTITY_FAILED_RESPONSE_TYPE = + 'WebConnectionProtocol5ValidateAppIdentityFailedResponse'; + +/** + * Returns true if the value has a type property with value 'WCP5ValidateAppIdentityResponse'. This is a fast check that does not check the format of the message + */ +export function isWebConnectionProtocol5ValidateAppIdentitySuccessResponse( + value: any +): value is WebConnectionProtocol5ValidateAppIdentitySuccessResponse { + return value != null && value.type === 'WCP5ValidateAppIdentityResponse'; +} + +/** + * Returns true if value is a valid WebConnectionProtocol5ValidateAppIdentitySuccessResponse. This checks the type against the json schema for the message and will be slower + */ +export function isValidWebConnectionProtocol5ValidateAppIdentitySuccessResponse( + value: any +): value is WebConnectionProtocol5ValidateAppIdentitySuccessResponse { + try { + Convert.webConnectionProtocol5ValidateAppIdentitySuccessResponseToJson(value); + return true; + } catch (_e: any) { + return false; + } +} + +export const WEB_CONNECTION_PROTOCOL5_VALIDATE_APP_IDENTITY_SUCCESS_RESPONSE_TYPE = + 'WebConnectionProtocol5ValidateAppIdentitySuccessResponse'; + +/** + * Returns true if the value has a type property with value 'WCP6Goodbye'. This is a fast check that does not check the format of the message + */ +export function isWebConnectionProtocol6Goodbye(value: any): value is WebConnectionProtocol6Goodbye { + return value != null && value.type === 'WCP6Goodbye'; +} + +/** + * Returns true if value is a valid WebConnectionProtocol6Goodbye. This checks the type against the json schema for the message and will be slower + */ +export function isValidWebConnectionProtocol6Goodbye(value: any): value is WebConnectionProtocol6Goodbye { + try { + Convert.webConnectionProtocol6GoodbyeToJson(value); + return true; + } catch (_e: any) { + return false; + } +} + +export const WEB_CONNECTION_PROTOCOL6_GOODBYE_TYPE = 'WebConnectionProtocol6Goodbye'; + +/** + * Returns true if value is a valid WebConnectionProtocolMessage. This checks the type against the json schema for the message and will be slower + */ +export function isValidWebConnectionProtocolMessage(value: any): value is WebConnectionProtocolMessage { + try { + Convert.webConnectionProtocolMessageToJson(value); + return true; + } catch (_e: any) { + return false; + } +} + +export const WEB_CONNECTION_PROTOCOL_MESSAGE_TYPE = 'WebConnectionProtocolMessage'; diff --git a/packages/fdc3-standard/src/api/GetAgent.ts b/packages/fdc3-standard/src/api/GetAgent.ts index 92d9ef1c1..6ec52df3d 100644 --- a/packages/fdc3-standard/src/api/GetAgent.ts +++ b/packages/fdc3-standard/src/api/GetAgent.ts @@ -81,6 +81,10 @@ export type GetAgentType = (params?: GetAgentParams) => Promise; * or an iframe's `contentWindow`) for a window or frame in which it has loaded * a Desktop Agent or suitable proxy to one that works with FDC3 Web Connection * and Desktop Agent Communication Protocols. + * + * @property {GetAgentLogSettings} logging Settings that determine what should + * will logged by the getAgent() implementation and DesktopAgentProxy to the + * JavaScript console. */ export type GetAgentParams = { timeoutMs?: number; @@ -89,6 +93,32 @@ export type GetAgentParams = { intentResolver?: boolean; dontSetWindowFdc3?: boolean; failover?: (args: GetAgentParams) => Promise; + logging?: GetAgentLogSettings; +}; + +/** + * @typedef {Object} GetAgentLogSettings Type representing parameters passed to the + * getAgent function that control what is logged to the JavaScript console by the + * getAgent() implementation and any DesktopAgentProxy implementations it creates. + * + * @property {boolean} connection Log-level messages relating to establishing a + * connection to the Desktop Agent (default true). + * + * @property {boolean} connectionDebug Debug-level messages relating to establishing + * a connection to the Desktop Agent (default false). + * + * @property {boolean} proxyDebug Debug-level messages that provide details of + * all messages sent to or received from the DesktopAgent (excluding heartbeat + * messages) by the DesktopAgentProxy (default false). + * + * @property {boolean} heartbeat Debug-level messages relating to heartbeat messages + * sent to or received from the DesktopAgent by the DesktopAgentProxy (default false). + */ +export type GetAgentLogSettings = { + connection: boolean; + connectionDebug: boolean; + proxyDebug: boolean; + heartbeat: boolean; }; /** Type representing data on the Desktop Agent that an app diff --git a/website/docs/api/ref/GetAgent.md b/website/docs/api/ref/GetAgent.md index 5e8626346..7d73ce82c 100644 --- a/website/docs/api/ref/GetAgent.md +++ b/website/docs/api/ref/GetAgent.md @@ -98,14 +98,44 @@ A small number of arguments are accepted that can affect the behavior of `getAge * or an iframe's `contentWindow`) for a window or frame in which it has loaded * a Desktop Agent or suitable proxy to one that works with FDC3 Web Connection * and Desktop Agent Communication Protocols. - */ + * + * @property {GetAgentLogSettings} logging Settings that determine what should + * will logged by the getAgent() implementation and DesktopAgentProxy to the + * JavaScript console. + */ type GetAgentParams = { timeoutMs?: number, identityUrl?: string, channelSelector?: boolean, intentResolver?: boolean, dontSetWindowFdc3?: boolean, - failover?: (args: GetAgentParams) => Promise + failover?: (args: GetAgentParams) => Promise + logging?: GetAgentLogSettings; +}; + +/** + * @typedef {Object} GetAgentLogSettings Type representing parameters passed to the + * getAgent function that control what is logged to the JavaScript console by the + * getAgent() implementation and any DesktopAgentProxy implementations it creates. + * + * @property {boolean} connection Log-level messages relating to establishing a + * connection to the Desktop Agent (default true). + * + * @property {boolean} connectionDebug Debug-level messages relating to establishing + * a connection to the Desktop Agent (default false). + * + * @property {boolean} proxyDebug Debug-level messages that provide details of + * all messages sent to or received from the DesktopAgent (excluding heartbeat + * messages) by the DesktopAgentProxy (default false). + * + * @property {boolean} heartbeat Debug-level messages relating to heartbeat messages + * sent to or received from the DesktopAgent by the DesktopAgentProxy (default false). + */ +export type GetAgentLogSettings = { + connection: boolean, + connectionDebug: boolean, + proxyDebug: boolean, + heartbeat: boolean }; ``` @@ -159,7 +189,13 @@ Failover functions MUST be asynchronous and MUST resolve to one of the following ## Persisted Connection Data -The `getAgent()` function uses [`SessionStorage`](https://html.spec.whatwg.org/multipage/webstorage.html) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)) to persist information on an instance of an app under the key `"FDC3-Desktop-Agent-Details"` and how it connected to a Desktop Agent in order to ensure a consistent connection type and `instanceId` when reconnecting after navigation or refresh events. Applications are not expected to interact with this information directly, rather it is set and used by the `getAgent()` implementation. +The `getAgent()` function uses [`SessionStorage`](https://html.spec.whatwg.org/multipage/webstorage.html) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)) to persist information on an instance of an app under the key `"FDC3-Desktop-Agent-Details"` and how it connected to a Desktop Agent in order to ensure a consistent connection type and `instanceId` when reconnecting after navigation or refresh events. + +:::info + +Applications are not expected to interact with this information directly, rather it is set and used by the `getAgent()` implementation. + +::: The details persisted conform to the following type: From 19a0f8ee6afd5c1e8b563481abd4ff5a002f50d1 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 15 Jan 2025 18:51:03 +0000 Subject: [PATCH 2/6] CHANGELOG --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d44c65f56..c130de935 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,7 +23,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added utility functions `isStandardContextType(contextType: string)`, `isStandardIntent(intent: string)`,`getPossibleContextsForIntent(intent: StandardIntent)`. ([#1139](https://github.com/finos/FDC3/pull/1139)) * Added support for event listening outside of intent or context listnener. Added new function `addEventListener`, type `EventHandler`, enum `FDC3EventType` and interfaces `FDC3Event` and `FDC3ChannelChangedEvent`. ([#1207](https://github.com/finos/FDC3/pull/1207)) * Added new `CreateOrUpdateProfile` intent. ([#1359](https://github.com/finos/FDC3/pull/1359)) -* Added separate `fdc3-commonjs` module for compatibility with older projects that use CommonJS. ([#1452](https://github.com/finos/FDC3/pull/1452)) +* Added separate `fdc3-commonjs` module for compatibility with older projects that use CommonJS. ([#1452](https://github.com/finos/FDC3/pull/1452)) +* Added the ability to control logging to the JS console from getAgent() and the DesktopAgentProxy via arguments to getAgent(). ([#1495](https://github.com/finos/FDC3/pull/1495)) ### Changed From a44ec5df582674318a83efabdf036d5f44470c92 Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 15 Jan 2025 18:56:09 +0000 Subject: [PATCH 3/6] Testing coverage --- packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts | 2 +- packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts b/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts index 0e81479a1..4ffb420fa 100644 --- a/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts +++ b/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts @@ -27,7 +27,7 @@ export abstract class AbstractFDC3Logger { /** This should be overridden by sub-classes to change the prefix applied * to log messages. */ static get prefix(): string { - return ''; + /* istanbul ignore next */ return ''; } public static enableDebugLogs(enable: boolean) { diff --git a/packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts b/packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts index b5a9b2d36..467223840 100644 --- a/packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts +++ b/packages/fdc3-agent-proxy/test/step-definitions/util.steps.ts @@ -66,6 +66,7 @@ When( const TEST_ERROR = 'Test error - This is expected on the console'; When('All log functions are used with a message', async function (this: CustomWorld) { + Logger.enableLogs(true); Logger.enableDebugLogs(true); Logger.enableHeartbeatLogs(true); Logger.debug('Debug msg'); @@ -76,6 +77,7 @@ When('All log functions are used with a message', async function (this: CustomWo }); When('All log functions are used with an error', async function (this: CustomWorld) { + Logger.enableLogs(true); Logger.enableDebugLogs(true); Logger.enableHeartbeatLogs(true); Logger.debug('debug-level error: ', new Error(TEST_ERROR)); From dca1f8a9c9d8c7b7cbbd33e90049b193e7cd836f Mon Sep 17 00:00:00 2001 From: Kris West Date: Wed, 15 Jan 2025 18:57:33 +0000 Subject: [PATCH 4/6] Test coverage --- packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts b/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts index 4ffb420fa..16a932d0e 100644 --- a/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts +++ b/packages/fdc3-agent-proxy/src/util/AbstractFDC3Logger.ts @@ -26,8 +26,8 @@ export abstract class AbstractFDC3Logger { /** This should be overridden by sub-classes to change the prefix applied * to log messages. */ - static get prefix(): string { - /* istanbul ignore next */ return ''; + /* istanbul ignore next */ static get prefix(): string { + return ''; } public static enableDebugLogs(enable: boolean) { From 1ed86d81df463dda15b47284ac3cb1c08c20f43c Mon Sep 17 00:00:00 2001 From: Kris West Date: Thu, 16 Jan 2025 16:30:10 +0000 Subject: [PATCH 5/6] Update website/docs/api/ref/GetAgent.md --- website/docs/api/ref/GetAgent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/api/ref/GetAgent.md b/website/docs/api/ref/GetAgent.md index 7d73ce82c..2b6ca4da8 100644 --- a/website/docs/api/ref/GetAgent.md +++ b/website/docs/api/ref/GetAgent.md @@ -109,7 +109,7 @@ type GetAgentParams = { channelSelector?: boolean, intentResolver?: boolean, dontSetWindowFdc3?: boolean, - failover?: (args: GetAgentParams) => Promise + failover?: (args: GetAgentParams) => Promise, logging?: GetAgentLogSettings; }; From 3ab5d4523c56fdb3252a5846c9f303873a92b7cd Mon Sep 17 00:00:00 2001 From: Kris West Date: Fri, 24 Jan 2025 20:33:20 +0000 Subject: [PATCH 6/6] Setup Logger on first call to getAgent --- packages/fdc3-get-agent/src/strategies/getAgent.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/fdc3-get-agent/src/strategies/getAgent.ts b/packages/fdc3-get-agent/src/strategies/getAgent.ts index 449846b28..5903ecf3b 100644 --- a/packages/fdc3-get-agent/src/strategies/getAgent.ts +++ b/packages/fdc3-get-agent/src/strategies/getAgent.ts @@ -34,6 +34,9 @@ export function clearAgentPromise() { } function initAgentPromise(options: GetAgentParams): Promise { + Logger.enableLogs(options.logging?.connection ?? true); + Logger.enableDebugLogs(options.logging?.connectionDebug ?? false); + Logger.log(`Initiating Desktop Agent discovery at ${new Date().toISOString()}`); let strategies: Loader[];