Refactor standard intents declaration to use union types instead of enums

Signed-off-by: Andrei Floricel <andrei.floricel@gmail.com>

Author: andreifloricel

src/api/DesktopAgent.ts

@@ -13,6 +13,7 @@ import { ImplementationMetadata } from './ImplementationMetadata';
 import { PrivateChannel } from './PrivateChannel';
 import { AppIdentifier } from './AppIdentifier';
 import { AppMetadata } from './AppMetadata';
+import { Intent } from '../intents/Intents';
 
 /**
  * A Desktop Agent is a desktop component (or aggregate of components) that serves as a
@@ -125,7 +126,7 @@ export interface DesktopAgent {
    * // }
    * ```
    */
-  findIntent(intent: string, context?: Context, resultType?: string): Promise<AppIntent>;
+  findIntent(intent: Intent, context?: Context, resultType?: string): Promise<AppIntent>;
 
   /**
    * Find all the available intents for a particular context, and optionally a desired result context type.
@@ -234,7 +235,7 @@ export interface DesktopAgent {
    *
    * If you wish to raise an Intent without a context, use the `fdc3.nothing` context type. This type exists so that apps can explicitly declare support for raising an intent without context.
    *
-   * Returns an `IntentResolution` object with details of the app instance that was selected (or started) to respond to the intent. 
+   * Returns an `IntentResolution` object with details of the app instance that was selected (or started) to respond to the intent.
    *
    * Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the `IntentResolution`. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object, Channel object or void that is provided as resolution within the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the `ResultError` enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a valid response (a promise or void), or (3) the returned promise resolves to an invalid type.
    *
@@ -268,7 +269,7 @@ export interface DesktopAgent {
    * }
    * ```
    */
-  raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise<IntentResolution>;
+  raiseIntent(intent: Intent, context: Context, app?: AppIdentifier): Promise<IntentResolution>;
 
   /**
    * Finds and raises an intent against apps registered with the desktop agent based on the type of the specified context data example.
@@ -346,7 +347,7 @@ export interface DesktopAgent {
    * });
    * ```
    */
-  addIntentListener(intent: string, handler: IntentHandler): Promise<Listener>;
+  addIntentListener(intent: Intent, handler: IntentHandler): Promise<Listener>;
 
   /**
    * Adds a listener for incoming context broadcasts from the Desktop Agent (via a User channel or `fdc3.open`API call. If the consumer is only interested in a context of a particular type, they can they can specify that type. If the consumer is able to receive context of any type or will inspect types received, then they can pass `null` as the `contextType` parameter to receive all context types.
@@ -561,7 +562,7 @@ export interface DesktopAgent {
    * await fdc3.raiseIntent("StartChat", context, appIntent.apps[0].name);
    * ```
    */
-  raiseIntent(intent: string, context: Context, name: string): Promise<IntentResolution>;
+  raiseIntent(intent: Intent, context: Context, name: string): Promise<IntentResolution>;
 
   /**
    * @deprecated version of `raiseIntentForContext` that targets an app by by name rather than `AppIdentifier`. Provided for backwards compatibility with versions FDC3 standard <2.0.

src/api/IntentMetadata.ts

@@ -3,12 +3,14 @@
  * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
+import { Intent } from '../intents/Intents';
+
 /**
  * Intent descriptor
  */
 export interface IntentMetadata {
   /** The unique name of the intent that can be invoked by the raiseIntent call */
-  readonly name: string;
+  readonly name: Intent;
 
   /** Display name for the intent.
    * @deprecated Use the intent name for display as display name may vary for

src/api/IntentResolution.ts

@@ -5,6 +5,7 @@
 
 import { IntentResult } from './Types';
 import { AppIdentifier } from './AppIdentifier';
+import { Intent } from '../intents/Intents';
 
 /**
  * IntentResolution provides a standard format for data returned upon resolving an intent.
@@ -43,7 +44,7 @@ export interface IntentResolution {
    * The intent that was raised. May be used to determine which intent the user
    * chose in response to `fdc3.raiseIntentForContext()`.
    */
-  readonly intent: string;
+  readonly intent: Intent;
   /**
    * The version number of the Intents schema being used.
    */

src/api/Methods.ts

@@ -14,6 +14,7 @@ import {
   ImplementationMetadata,
   AppMetadata,
   PrivateChannel,
+  Intent,
 } from '..';
 
 const DEFAULT_TIMEOUT = 5000;
@@ -74,7 +75,7 @@ export function open(app: AppIdentifier | string, context?: Context): Promise<Ap
   }
 }
 
-export function findIntent(intent: string, context?: Context, resultType?: string): Promise<AppIntent> {
+export function findIntent(intent: Intent, context?: Context, resultType?: string): Promise<AppIntent> {
   return rejectIfNoGlobal(() => window.fdc3.findIntent(intent, context, resultType));
 }
 
@@ -86,7 +87,7 @@ export function broadcast(context: Context): Promise<void> {
   return rejectIfNoGlobal(() => window.fdc3.broadcast(context));
 }
 
-export function raiseIntent(intent: string, context: Context, app?: AppIdentifier | string): Promise<IntentResolution> {
+export function raiseIntent(intent: Intent, context: Context, app?: AppIdentifier | string): Promise<IntentResolution> {
   if (isString(app)) {
     return rejectIfNoGlobal(() => window.fdc3.raiseIntent(intent, context, app));
   } else {
@@ -102,7 +103,7 @@ export function raiseIntentForContext(context: Context, app?: AppIdentifier | st
   }
 }
 
-export function addIntentListener(intent: string, handler: IntentHandler): Promise<Listener> {
+export function addIntentListener(intent: Intent, handler: IntentHandler): Promise<Listener> {
   return rejectIfNoGlobal(() => window.fdc3.addIntentListener(intent, handler));
 }
 

src/bridging/BridgingTypes.ts

@@ -75,6 +75,8 @@
 // These functions will throw an error if the JSON doesn't
 // match the expected interface, even if the JSON is valid.
 
+import { Intent } from '../intents/Intents';
+
 /**
  * Metadata relating to the FDC3 Desktop Agent implementation and its provider.
  */
@@ -1770,7 +1772,7 @@ export interface FindIntentAgentRequestMeta {
  */
 export interface FindIntentAgentRequestPayload {
   context?: ContextElement;
-  intent: string;
+  intent: Intent;
   resultType?: string;
 }
 
@@ -1844,7 +1846,7 @@ export interface IntentMetadata {
   /**
    * The unique name of the intent that can be invoked by the raiseIntent call
    */
-  name: string;
+  name: Intent;
 }
 
 /**
@@ -1929,7 +1931,7 @@ export interface FindIntentBridgeRequestMeta {
  */
 export interface FindIntentBridgeRequestPayload {
   context?: ContextElement;
-  intent: string;
+  intent: Intent;
   resultType?: string;
 }
 
@@ -3697,7 +3699,7 @@ export interface RaiseIntentAgentRequestMeta {
 export interface RaiseIntentAgentRequestPayload {
   app: AppDestinationIdentifier;
   context: ContextElement;
-  intent: string;
+  intent: Intent;
 }
 
 /**
@@ -3774,7 +3776,7 @@ 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;
+  intent: 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
@@ -3870,7 +3872,7 @@ export interface RaiseIntentBridgeRequestMeta {
 export interface RaiseIntentBridgeRequestPayload {
   app: AppDestinationIdentifier;
   context: ContextElement;
-  intent: string;
+  intent: Intent;
 }
 
 /**

src/intents/Intents.ts

@@ -2,23 +2,31 @@
  * SPDX-License-Identifier: Apache-2.0
  * Copyright FINOS FDC3 contributors - see NOTICE file
  */
-export enum Intents {
-  CreateInteraction = 'CreateInteraction',
-  SendChatMessage = 'SendChatMessage',
-  StartCall = 'StartCall',
-  StartChat = 'StartChat',
-  StartEmail = 'StartEmail',
-  ViewAnalysis = 'ViewAnalysis',
-  ViewChat = 'ViewChat',
-  ViewChart = 'ViewChart',
-  ViewContact = 'ViewContact',
-  ViewHoldings = 'ViewHoldings',
-  ViewInstrument = 'ViewInstrument',
-  ViewInteractions = 'ViewInteractions',
-  ViewMessages = 'ViewMessages',
-  ViewNews = 'ViewNews',
-  ViewOrders = 'ViewOrders',
-  ViewProfile = 'ViewProfile',
-  ViewQuote = 'ViewQuote',
-  ViewResearch = 'ViewResearch',
-}
+
+/**
+ * @see https://fdc3.finos.org/docs/intents/spec#standard-intents
+ */
+export type StandardIntent =
+  | 'CreateInteraction'
+  | 'SendChatMessage'
+  | 'StartCall'
+  | 'StartChat'
+  | 'StartEmail'
+  | 'ViewAnalysis'
+  | 'ViewChat'
+  | 'ViewChart'
+  | 'ViewContact'
+  | 'ViewHoldings'
+  | 'ViewInstrument'
+  | 'ViewInteractions'
+  | 'ViewMessages'
+  | 'ViewNews'
+  | 'ViewOrders'
+  | 'ViewProfile'
+  | 'ViewQuote'
+  | 'ViewResearch';
+
+/**
+ * @see https://fdc3.finos.org/docs/intents/spec
+ */
+export type Intent = StandardIntent | (string & {});