FDC3 API Metadata

Contributing_Guide.md

@@ -0,0 +1,7 @@
+# What you need to update if you want to do _
+
+## Add arguments to existing methods
+
+## Create new methods
+
+## Deprecate existing methods

packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts

@@ -1,6 +1,7 @@
 import {
   AppIdentifier,
   AppMetadata,
+  AppProvidableContextMetadata,
   ContextHandler,
   DesktopAgent,
   EventHandler,
@@ -88,10 +89,10 @@ export class DesktopAgentProxy implements DesktopAgent, Connectable {
     return this.apps.getImplementationMetadata();
   }
 
-  async broadcast(context: Context): Promise<void> {
+  async broadcast(context: Context, metadata?: AppProvidableContextMetadata): Promise<void> {
     const channel = await this.channels.getUserChannel();
     if (channel) {
-      return channel.broadcast(context);
+      return channel.broadcast(context, metadata);
     } else {
       return Promise.resolve();
     }
@@ -175,20 +176,24 @@ export class DesktopAgentProxy implements DesktopAgent, Connectable {
     }
   }
 
-  raiseIntent(intent: string, context: Context, app?: string | AppIdentifier) {
-    return this.intents.raiseIntent(intent, context, this.ensureAppId(app));
+  raiseIntent(intent: string, context: Context, app?: string | AppIdentifier, metadata?: AppProvidableContextMetadata) {
+    return this.intents.raiseIntent(intent, context, this.ensureAppId(app), metadata);
   }
 
   addIntentListener(intent: string, handler: IntentHandler) {
     return this.intents.addIntentListener(intent, handler);
   }
 
-  raiseIntentForContext(context: Context, app?: string | AppIdentifier): Promise<IntentResolution> {
-    return this.intents.raiseIntentForContext(context, this.ensureAppId(app));
+  raiseIntentForContext(
+    context: Context,
+    app?: string | AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution> {
+    return this.intents.raiseIntentForContext(context, this.ensureAppId(app), metadata);
   }
 
-  open(app: string | AppIdentifier, context?: Context | undefined) {
-    return this.apps.open(this.ensureAppId(app)!, context);
+  open(app: string | AppIdentifier, context?: Context, metadata?: AppProvidableContextMetadata) {
+    return this.apps.open(this.ensureAppId(app)!, context, metadata);
   }
 
   findInstances(app: AppIdentifier) {

packages/fdc3-agent-proxy/src/apps/AppSupport.ts

@@ -1,9 +1,9 @@
-import { AppIdentifier, AppMetadata, ImplementationMetadata } from '@finos/fdc3-standard';
+import { AppIdentifier, AppMetadata, AppProvidableContextMetadata, ImplementationMetadata } from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 
 export interface AppSupport {
   findInstances(app: AppIdentifier): Promise<Array<AppIdentifier>>;
   getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;
-  open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
+  open(app: AppIdentifier, context?: Context, metadata?: AppProvidableContextMetadata): Promise<AppIdentifier>;
   getImplementationMetadata(): Promise<ImplementationMetadata>;
 }

packages/fdc3-agent-proxy/src/apps/DefaultAppSupport.ts

@@ -1,4 +1,11 @@
-import { AppIdentifier, AppMetadata, ImplementationMetadata, OpenError, ResolveError } from '@finos/fdc3-standard';
+import {
+  AppIdentifier,
+  AppMetadata,
+  AppProvidableContextMetadata,
+  ImplementationMetadata,
+  OpenError,
+  ResolveError,
+} from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 import { AppSupport } from './AppSupport';
 import { Messaging } from '../Messaging';
@@ -68,7 +75,11 @@ export class DefaultAppSupport implements AppSupport {
     return response.payload.appMetadata!;
   }
 
-  async open(app: AppIdentifier, context?: Context | undefined): Promise<AppIdentifier> {
+  async open(
+    app: AppIdentifier,
+    context?: Context | undefined,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<AppIdentifier> {
     const request: OpenRequest = {
       type: 'openRequest',
       payload: {
@@ -78,6 +89,7 @@ export class DefaultAppSupport implements AppSupport {
         },
         context,
       },
+      metadata,
       meta: this.messaging.createMeta(),
     };
 

packages/fdc3-agent-proxy/src/intents/DefaultIntentSupport.ts

@@ -8,6 +8,7 @@ import {
   IntentResult,
   IntentResolver,
   IntentResolutionChoice,
+  AppProvidableContextMetadata,
 } from '@finos/fdc3-standard';
 import { IntentSupport } from './IntentSupport';
 import { Messaging } from '../Messaging';
@@ -28,6 +29,7 @@ import {
   RaiseIntentResultResponse,
 } from '@finos/fdc3-schema/dist/generated/api/BrowserTypes';
 import { throwIfUndefined } from '../util/throwIfUndefined';
+import { v4 } from 'uuid';
 
 const convertIntentResult = async (
   { payload }: RaiseIntentResultResponse,
@@ -130,16 +132,24 @@ export class DefaultIntentSupport implements IntentSupport {
     return ir;
   }
 
-  async raiseIntent(intent: string, context: Context, app: AppIdentifier): Promise<IntentResolution> {
+  async raiseIntent(
+    intent: string,
+    context: Context,
+    app: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution> {
     const meta = this.messaging.createMeta();
     const request: RaiseIntentRequest = {
       type: 'raiseIntentRequest',
       payload: {
         intent,
         context,
-        app: app,
+        app,
+        metadata: {
+          traceId: metadata?.traceId ?? v4(),
+        },
       },
-      meta: meta,
+      meta,
     };
 
     const resultPromise = this.createResultPromise(request);
@@ -163,7 +173,7 @@ export class DefaultIntentSupport implements IntentSupport {
         context
       );
       if (result) {
-        return this.raiseIntent(intent, context, result.appId);
+        return this.raiseIntent(intent, context, result.appId, metadata);
       } else {
         throw new Error(ResolveError.UserCancelled);
       }
@@ -174,14 +184,22 @@ export class DefaultIntentSupport implements IntentSupport {
     }
   }
 
-  async raiseIntentForContext(context: Context, app?: AppIdentifier | undefined): Promise<IntentResolution> {
+  async raiseIntentForContext(
+    context: Context,
+    app?: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution> {
+    const meta = this.messaging.createMeta();
     const request: RaiseIntentForContextRequest = {
       type: 'raiseIntentForContextRequest',
       payload: {
         context,
-        app: app,
+        app,
       },
-      meta: this.messaging.createMeta(),
+      metadata: {
+        traceId: metadata?.traceId ?? v4(),
+      },
+      meta,
     };
 
     const resultPromise = this.createResultPromise(request);

packages/fdc3-agent-proxy/src/intents/IntentSupport.ts

@@ -1,10 +1,26 @@
-import { AppIdentifier, AppIntent, IntentHandler, IntentResolution, Listener } from '@finos/fdc3-standard';
+import {
+  AppIdentifier,
+  AppIntent,
+  AppProvidableContextMetadata,
+  IntentHandler,
+  IntentResolution,
+  Listener,
+} from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 
 export interface IntentSupport {
   findIntent(intent: string, context: Context, resultType: string | undefined): Promise<AppIntent>;
   findIntentsByContext(context: Context): Promise<AppIntent[]>;
-  raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise<IntentResolution>;
-  raiseIntentForContext(context: Context, app?: AppIdentifier): Promise<IntentResolution>;
+  raiseIntent(
+    intent: string,
+    context: Context,
+    app?: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution>;
+  raiseIntentForContext(
+    context: Context,
+    app?: AppIdentifier,
+    metadata?: AppProvidableContextMetadata
+  ): Promise<IntentResolution>;
   addIntentListener(intent: string, handler: IntentHandler): Promise<Listener>;
 }

packages/fdc3-agent-proxy/src/listeners/DefaultContextListener.ts

@@ -1,4 +1,4 @@
-import { ContextHandler, Channel } from '@finos/fdc3-standard';
+import { ContextHandler, Channel, DesktopAgentProvidableContextMetadata } from '@finos/fdc3-standard';
 import { Messaging } from '../Messaging';
 import { AbstractListener } from './AbstractListener';
 import { UserChannelContextListener } from './UserChannelContextListener';
@@ -57,6 +57,11 @@ export class DefaultContextListener
   }
 
   action(m: BroadcastEvent): void {
-    this.handler(m.payload.context);
+    const metadata: DesktopAgentProvidableContextMetadata = {
+      source: m.payload.originatingApp,
+      timestamp: m.meta.timestamp,
+      traceId: m.metadata?.traceId,
+    };
+    this.handler(m.payload.context, metadata);
   }
 }

packages/fdc3-agent-proxy/src/listeners/DefaultIntentListener.ts

@@ -9,6 +9,7 @@ import {
   IntentResultResponse,
   //RaiseIntentResponse,
 } from '@finos/fdc3-schema/dist/generated/api/BrowserTypes';
+import { v4 } from 'uuid';
 
 export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIntentListenerRequest> {
   readonly intent: string;
@@ -34,6 +35,8 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
   action(m: IntentEvent): void {
     const done = this.handler(m.payload.context, {
       source: m.payload.originatingApp as AppIdentifier,
+      timestamp: m.meta.timestamp,
+      traceId: m.metadata?.traceId ?? v4(),
     });
 
     this.handleIntentResult(done, m);
@@ -51,6 +54,7 @@ export class DefaultIntentListener extends AbstractListener<IntentHandler, AddIn
         intentEventUuid: m.meta.eventUuid,
         raiseIntentRequestUuid: m.payload.raiseIntentRequestUuid,
       },
+      metadata: m.metadata,
     };
 
     return out;