[SERVICE-542] Refresh FDC3 API docs

src/client/context.ts

@@ -5,25 +5,24 @@
 /**
  * TypeScript definitions for envelope and context objects.
  *
- * These structures are defined by the Contexts FDC3 working group. he definitions here are based on current
- * proposals and are not final. There may be minor differences between the current spec and the definitions here,
- * in order to support this demo.
+ * These structures are defined by the Contexts FDC3 working group.
  */
 
 /**
- * General-purpose context type
- *
- * A context object is open for extension with any custom properties/metadata.
+ * General-purpose context type, as defined by [FDC3](https://fdc3.finos.org/docs/1.0/context-intro).
+ * A context object is a well-understood datum that is streamable between FDC3 participants. As a result
+ * it has a field describing what type it is, and data indicating its identity. Use this as a base
+ * to derive your own with any custom properties or metadata.
  */
 export interface Context {
     /**
-     * The type of the context that uniquely identifies it, e.g. "fdc3.instrument"
-     * Used to refer to the accepted context(s) when declaring intents.
+     * The type of the context that uniquely identifies it, e.g. "fdc3.instrument".
+     * This is used to refer to the accepted context(s) when declaring intents. See [[AppDirIntent]].
      */
     type: string;
 
     /**
-     * The name of the context data (optional).
+     * The name of the context data (optional). This is a text string that describes the data being sent.
      * Implementors of context may choose to make the name mandatory.
      */
     name?: string;
@@ -35,22 +34,72 @@ export interface Context {
     id?: {[key: string]: string|undefined;};
 
     /**
-     * A context object is open for extension with any custom properties/metadata.
+     * @hidden
+     * Custom properties and metadata. This can be extended in specific context object.
      */
     [key: string]: unknown;
 }
 
-// Built-in contexts
+/**
+ * Built-in context to define a contact.
+ */
 export interface ContactContext extends Context {
+    /**
+     * The context type is always 'fdc3.contact'.
+     */
     type: 'fdc3.contact';
+    /**
+     * Free text name of the contact.
+     */
     name: string;
+    /**
+     * The contact data. Can contain email address, Twitter handle, and phone number.
+     */
     id: {[key: string]: string}&{email?: string; twitter?: string; phone?: string};
 }
-export interface SecurityContext extends Context {
-    type: 'fdc3.security';
-    id: {[key: string]: string}&{default: string};
+
+/**
+ * Built-in context to define a financial instrument.
+ */
+export interface InstrumentContext extends Context {
+    /**
+     * The context type is always 'fdc3.instrument'.
+     */
+    type: 'fdc3.instrument';
+    /**
+     * Optional free text name of the instrument.
+     */
+    name?: string;
+    /**
+     * Can contain some or all of
+     * * a ticker,
+     * * an [ISIN](https://www.isin.org/isin/),
+     * * a [CUSIP](https://www.cusip.com/cusip/index.htm),
+     * * a [SEDOL](https://www.londonstockexchange.com/products-and-services/reference-data/sedol-master-file/sedol-master-file.htm),
+     * * a [Reuters Instrument Code (RIC)](https://en.wikipedia.org/wiki/Reuters_Instrument_Code),
+     * * a [Bloomberg Ticker](https://www.bloomberg.com/professional/product/market-data/),
+     * * a [PERMID](https://permid.org/),
+     * * and a [FIGI](https://www.openfigi.com/about/figi).
+     */
+    id: {[key: string]: string}&{ticker?: string; ISIN?: string; CUSIP?: string; SEDOL?: string;
+        RIC?: string; BBG?: string; PERMID?: string; FIGI?: string;};
 }
+
+/**
+ * Built-in context to define an organization.
+ */
 export interface OrganizationContext extends Context {
+    /**
+     * The context type is always fdc3.organization.
+     */
     type: 'fdc3.organization';
-    id: {[key: string]: string}&{default: string};
+    /**
+     * Optional free text name of the organization.
+     */
+    name?: string;
+    /**
+     * Can contain either or both an [LEI](https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei)
+     * and a [PERMID](https://permid.org/).
+     */
+    id: {[key: string]: string}&{LEI?: string; PERMID?: string};
 }

src/client/contextChannels.ts

@@ -30,7 +30,7 @@ export type FDC3ChannelEvent = ChannelWindowAddedEvent | ChannelWindowRemovedEve
 export type FDC3ChannelEventType = FDC3ChannelEvent['type'];
 
 /**
- * Event fired when a window is added to a channel. See {@link Channel.addEventListener}.
+ * Event fired when a window is added to a channel. See {@link ChannelBase.addEventListener}.
  *
  * Note that this event will typically fire as part of a pair - since windows must always belong to a channel, a window
  * can only join a channel by leaving it's previous channel. The exceptions to this rule are when the window is created
@@ -47,7 +47,7 @@ export interface ChannelWindowAddedEvent {
     identity: Identity;
 
     /**
-     * The channel that window now belongs to. Will always be the channel object that {@link Channel.addEventListener} was
+     * The channel that window now belongs to. Will always be the channel object that {@link ChannelBase.addEventListener} was
      * called on.
      */
     channel: Channel;
@@ -61,7 +61,7 @@ export interface ChannelWindowAddedEvent {
 }
 
 /**
- * Event fired when a window is removed from a channel. See {@link Channel.addEventListener}.
+ * Event fired when a window is removed from a channel. See {@link ChannelBase.addEventListener}.
  *
  * Note that this event will typically fire as part of a pair - since windows must always belong to a channel, a window
  * can only join a channel by leaving it's previous channel. The exceptions to this rule are when the window is created
@@ -87,7 +87,7 @@ export interface ChannelWindowRemovedEvent {
     channel: Channel | null;
 
     /**
-     * The channel that the window belonged to previously. Will always be the channel object that {@link Channel.addEventListener} was
+     * The channel that the window belonged to previously. Will always be the channel object that {@link ChannelBase.addEventListener} was
      * called on.
      */
     previousChannel: Channel;
@@ -335,7 +335,7 @@ export class DesktopChannel extends ChannelBase {
     public readonly color: number;
 
     /**
-     * @hidden
+     * @hideconstructor
      */
     public constructor(transport: DesktopChannelTransport) {
         super(transport.id, 'desktop');
@@ -355,7 +355,7 @@ export class DefaultChannel extends ChannelBase {
     public readonly type!: 'default';
 
     /**
-     * @hidden
+     * @hideconstructor
      */
     public constructor() {
         super(DEFAULT_CHANNEL_ID, 'default');