@openfin/core 25.68.26

package/src/api/interop/InteropClient.d.ts

@@ -0,0 +1,268 @@
+import Transport from '../../transport/transport';
+import { Base } from '../base';
+/**
+ * @typedef { object } Intent
+ * @summary The combination of an action and a context that is passed to an application for resolution.
+ * @property { string } name Name of the intent.
+ * @property { Context } context Data associated with the intent
+ */
+/**
+ * @typedef { object } Subscription
+ * @summary Object returned when subscribing a handler.
+ * @property { function } unsubscribe Function to unsubscribe the handler.
+ */
+/**
+ * @typedef { function } ContextHandler
+ * @summary Subscription function for addContextHandler.
+ */
+/**
+ * @typedef { function } IntentHandler
+ * @summary Subscription function for registerIntentHandler
+ */
+/**
+ * @typedef { object } ClientIdentity
+ * @summary The Identity for a Channel Client. Includes endpointId to differentiate between different connections for an entity.
+ * @property {string} uuid GUID of an application.
+ * @property {string} name Name of an entity in an application.
+ * @property {string} endpointId Unique differentiator for different Channel connections for an entity.
+ */
+/**
+ * @typedef { object } ContextGroupInfo
+ * @summary Information for a Context Group. Contains metadata for displaying the group properly.
+ * @property {string} id Name of the context group
+ * @property {DisplayMetadata} displayMetadata Metadata for the Context Group. Contains the group's human-readable name, color, and an image, as defined by the Interop Broker.
+ */
+/**
+ * @typedef { object } DisplayMetadata
+ * @summary The display data for a Context Group.
+ * @property {string} name A user-readable name for this context group, e.g: `"Red"`
+ * @property {string} [color] The color that should be associated within this context group when displaying this context group in a UI, e.g: `0xFF0000`.
+ * @property {string} [glyph] A URL of an image that can be used to display this context group
+ */
+/**
+ * @typedef { object } Context
+ * @summary Data passed between entities and applications.
+ * @property {object} [id] An object containing string key-value pairs for the bulk of the data for the context. Differs between context types.
+ * @property {string} [name] User-readable name for the incoming context.
+ * @property {string} type Conserved type for the context (e.g. `instrument` or `country`)
+ */
+/**
+ * @typedef { object } ContextForIntent
+ * @summary Data passed between entities and applications, including an optional metadata.
+ * @property {object} [id] An object containing string key-value pairs for the bulk of the data for the context. Differs between context types.
+ * @property {string} [name] User-readable name for the incoming context.
+ * @property {string} type Conserved type for the context (e.g. `instrument` or `country`)
+ * @property {any} [metadata]
+ */
+/**
+ * @typedef { object } SessionContextGroup
+ * @summary An instance of a SessionContextGroup
+ * @property {string} id The SessionContextGroup's id.
+ * @property {setContext} setContext Sets a context of a certain type
+ * @property {getCurrentContext} getCurrentContext Gets the currently set context of a certain type
+ * @property {addContextHandler} addContextHandler Adds a handler for context change.
+ */
+/**
+ * @typedef {function} setContext
+ * @summary A SessionContextGroup instance method for setting a context in the SessionContextGroup.
+ * @param {Context} context The Context to be set.
+ * @return {Promise<void>}
+ */
+/**
+ * @typedef {function} getCurrentContext
+ * @summary A SessionContextGroup instance method for getting the current context of a certain type.
+ * @param {string} [contextType] The Context Type to get. If not specified the last contextType set would get used.
+ * @return {Promise<Context>}
+ */
+/**
+ * @typedef {function} addContextHandler
+ * @summary A SessionContextGroup instance method for adding a handler for context change.
+ * @param {ContextHandler} contextHandler The callback to be invoked. Is invoked when (a) the context changes or (b) immediately after getting created if the context is already set.
+ * @param {string} [contextType] The context type this handler should listen to. If not specified, a global handler for all context types will get created. Only one global handler is allowed per SessionContextGroup.
+ * @return {Promise<void>}
+ */
+/**
+ * {@link https://developers.openfin.co/of-docs/docs/enable-color-linking **THE INTEROP API IS EXPERIMENTAL. IF YOU WOULD LIKE TO USE IT, PLEASE USE OUR DEFAULT IMPLEMENTATION IN BROWSER**}
+ *
+ * The Interop Client API is broken up into two groups:
+ *
+ * **Content Facing APIs** - For Application Developers putting Views into a Platform Window, who care about Context. These are APIs that send out and receive the Context data that flows between applications. Think of this as the Water in the Interop Pipes.
+ *
+ * **Context Grouping APIs** - For Platform Developers, to add and remove Views to and from Context Groups. These APIs are utilized under-the-hood in Platforms, so they don't need to be used to participate in Interop. These are the APIs that decide which entities the context data flows between. Think of these as the valves or pipes that control the flow of Context Data for Interop.
+ *
+ * ---
+ *
+ * All APIs are available at the `fin.me.interop` namespace.
+ *
+ * ---
+ *
+ * **You only need 2 things to participate in Interop Context Grouping:**
+ * * A Context Handler for incoming context: {@link InteropClient#addContextHandler addContextHandler(handler, contextType?)}
+ * * Call setContext on your context group when you want to share context with other group members: {@link InteropClient#setContext setContext(context)}
+ *
+ * ---
+ *
+ * ##### Constructor
+ * Returned by {@link Interop.connectSync Interop.connectSync}.
+ *
+ * ---
+ *
+ * ##### Interop methods intended for Views
+ *
+ *
+ * **Context Groups API**
+ *  * {@link InteropClient#addContextHandler addContextHandler(handler, contextType?)}
+ *  * {@link InteropClient#setContext setContext(context)}
+ *  * {@link InteropClient#getCurrentContext getCurrentContext(contextType?)}
+ *  * {@link InteropClient#joinSessionContextGroup joinSessionContextGroup(sessionContextGroupId)}
+ *
+ *
+ * **Intents API**
+ *  * {@link InteropClient#fireIntent fireIntent(intent)}
+ *  * {@link InteropClient#registerIntentHandler registerIntentHandler(intentHandler, intentName)}
+ *  * {@link InteropClient#getInfoForIntent getInfoForIntent(infoForIntentOptions)}
+ *  * {@link InteropClient#getInfoForIntentsByContext getInfoForIntentsByContext(context)}
+ *  * {@link InteropClient#fireIntentForContext fireIntentForContext(contextForIntent)}
+ *
+ * ##### Interop methods intended for Windows
+ *  * {@link InteropClient#getContextGroups getContextGroups()}
+ *  * {@link InteropClient#joinContextGroup joinContextGroup(contextGroupId, target?)}
+ *  * {@link InteropClient#removeFromContextGroup removeFromContextGroup(target?)}
+ *  * {@link InteropClient#getInfoForContextGroup getInfoForContextGroup(contextGroupId)}
+ *  * {@link InteropClient#getAllClientsInContextGroup getAllClientsInContextGroup(contextGroupId)}
+ *
+
+ *
+ * @hideconstructor
+ * @class
+ */
+export declare class InteropClient extends Base {
+    #private;
+    constructor(wire: Transport, name: string, interopConfig: OpenFin.InteropConfig);
+    /**
+     * Sets a context for the context group of the current entity.
+     * @param { Context } context - New context to set.
+     * @return { Promise<void> }
+     * @tutorial interop.setContext
+     */
+    setContext(context: OpenFin.Context): Promise<void>;
+    /**
+     * Add a context handler for incoming context. If an entity is part of a context group, and then sets its context handler, it will receive all of its declared contexts.
+     * @param { ContextHandler } handler - Handler for incoming context.
+     * @param { string } [contextType] - The type of context you wish to handle.
+     * @return { Promise<Subscription> }
+     * @tutorial interop.addContextHandler
+     */
+    addContextHandler(handler: OpenFin.ContextHandler, contextType?: string): Promise<{
+        unsubscribe: () => void;
+    }>;
+    /**
+     * Returns the Interop-Broker-defined context groups available for an entity to join.
+     * Used by Platform Windows.
+     * @return { Promise<ContextGroupInfo[]>}
+     * @tutorial interop.getContextGroups
+     */
+    getContextGroups(): Promise<OpenFin.ContextGroupInfo[]>;
+    /**
+     * Join all Interop Clients at the given identity to context group `contextGroupId`.
+     * If no target is specified, it adds the sender to the context group.
+     * Because multiple Channel connections/Interop Clients can potentially exist at a `uuid`/`name` combo, we currently join all Channel connections/Interop Clients at the given identity to the context group.
+     * If an `endpointId` is provided (which is unlikely, unless the call is coming from an external adapter), then we only join that single connection to the context group.
+     * For all intents and purposes, there will only be 1 connection present in Platform and Browser implmentations, so this point is more-or-less moot.
+     * Used by Platform Windows.
+     * @param { string } contextGroupId - Id of the context group.
+     * @param { Identity } [target] - Identity of the entity you wish to join to a context group.
+     * @return { Promise<void>}
+     * @tutorial interop.joinContextGroup
+     */
+    joinContextGroup(contextGroupId: string, target?: OpenFin.Identity): Promise<void>;
+    /**
+     * Removes the specified target from a context group.
+     * If no target is specified, it removes the sender from their context group.
+     * Used by Platform Windows.
+     * @param { Identity } [target] - Identity of the entity you wish to join to a context group.
+     * @return { Promise<void>}
+     * @tutorial interop.removeFromContextGroup
+     */
+    removeFromContextGroup(target?: OpenFin.Identity): Promise<void>;
+    /**
+     * Gets all clients for a context group.
+     * Used by Platform Windows.
+     * @param { string } contextGroupId - The id of context group you wish to get clients for.
+     * @return { Promise<ClientIdentity[]>}
+     * @tutorial interop.getAllClientsInContextGroup
+     */
+    getAllClientsInContextGroup(contextGroupId: string): Promise<OpenFin.ClientIdentity[]>;
+    /**
+     * Gets display info for a context group
+     * Used by Platform Windows.
+     * @param { string } contextGroupId - The id of context group you wish to get display info for.
+     * @return { Promise<ContextGroupInfo>}
+     * @tutorial interop.getInfoForContextGroup
+     */
+    getInfoForContextGroup(contextGroupId: string): Promise<OpenFin.ContextGroupInfo | undefined>;
+    /**
+     * Sends an intent to the Interop Broker to resolve.
+     * @param { Intent } intent - The combination of an action and a context that is passed to an application for resolution.
+     * @return { Promise<unknown>}
+     * @tutorial interop.fireIntent
+     * @experimental
+     */
+    fireIntent(intent: OpenFin.Intent): Promise<unknown>;
+    /**
+     * Adds an intent handler for incoming intents. The last intent sent of the name subscribed to will be received.
+     * @param { IntentHandler } handler - Registered function meant to handle a specific intent type.
+     * @param { string } intentName - The name of an intent.
+     * @return { Promise<Subscription> }
+     * @tutorial interop.registerIntentHandler
+     * @experimental
+     */
+    registerIntentHandler(handler: OpenFin.IntentHandler, intentName: string): Promise<{
+        unsubscribe: () => Promise<void>;
+    }>;
+    /**
+     * Gets the last context of the Context Group currently subscribed to. It takes an optional Context Type and returns the
+     * last context of that type.
+     * @param { string } [contextType]
+     * @return { Promise<Context> }
+     * @tutorial interop.getCurrentContext
+     * @experimental
+     */
+    getCurrentContext(contextType?: string): Promise<OpenFin.Context>;
+    /**
+     * Get information for a particular Intent from the Interop Broker.
+     * @param { InfoForIntentOptions } options
+     * @return { Promise<unknown> }
+     * @tutorial interop.getInfoForIntent
+     * @experimental
+     */
+    getInfoForIntent(options: OpenFin.InfoForIntentOptions): Promise<unknown>;
+    /**
+     * Get information from the Interop Broker on all Intents that are meant to handle a particular context.
+     * @param { Context } context
+     * @return { Promise<unknown> }
+     * @tutorial interop.getInfoForIntentsByContext
+     * @experimental
+     */
+    getInfoForIntentsByContext(context: OpenFin.Context): Promise<unknown>;
+    /**
+     * Sends a Context that will be resolved to an Intent by the Interop Broker.
+     * This context accepts a metadata property.
+     * @param { ContextForIntent } context
+     * @return { Promise<unknown> }
+     * @tutorial interop.fireIntentForContext
+     * @experimental
+     */
+    fireIntentForContext(context: OpenFin.ContextForIntent): Promise<unknown>;
+    /**
+     * Join the current entity to session context group `sessionContextGroupId` and return a sessionContextGroup instance.
+     * If the sessionContextGroup doesn't exist, one will get created.
+     * Session Context Groups do not persist between runs and aren't present on snapshots.
+     * @param { string } sessionContextGroupId - Id of the context group.
+     * @return { Promise<SessionContextGroup>}
+     * @tutorial interop.joinSessionContextGroup
+     * @experimental
+     */
+    joinSessionContextGroup(sessionContextGroupId: string): Promise<OpenFin.SessionContextGroup>;
+    private wrapIntentHandler;
+}