@unblu/embedded-app-component 7.37.2

package/dist/lib/shared/conversation.d.ts

@@ -0,0 +1,320 @@
+import { CallState } from './model/call-state';
+import { ConversationEventType, ConversationModule } from './internal/module/conversation-module';
+import { Listener } from './internal/util/event-emitter';
+import { ConversationState } from './model/conversation-state';
+import { ConnectionState } from './model/connection-state';
+import { Invitation } from "./model/invitation";
+import { CustomActionInvocation } from './model/customaction/custom-action-invocation';
+export type ConnectionStateListener = (connectionState: ConnectionState) => void;
+export type ConversationStateListener = (conversationState: ConversationState) => void;
+export type CallStateListener = (callState: CallState) => void;
+export type InvitationsListener = (invitations: Invitation[]) => void;
+/**
+ * Listener called whenever a custom action invocation triggers an API event for the client
+ * @param customActionInvocation The details of the custom action invocation
+ */
+export type CustomActionInvocationListener = (customActionInvocation: CustomActionInvocation) => void;
+/**
+ * #### This class gives API access to the currently active conversation.
+ *
+ * As long as a conversation is active one can register and receive the events provided by this class and call the methods.
+ * Once the conversation is closed this API object will be destroyed and no more event callbacks will be called.
+ * Any subsequent calls will fail.
+ *
+ * Use the {@link CLOSE} event to de-init any code connected to this conversation.
+ */
+export declare class Conversation {
+    private conversationModule;
+    private conversationId;
+    /**
+     * Event emitted when the {@link ConnectionState} of this conversation changes.
+     * @event connectionStateChange
+     * @see {@link on} for listener registration
+     */
+    static readonly CONNECTION_STATE_CHANGE: 'connectionStateChange';
+    /**
+     * Event emitted when the {@link ConversationState} of this conversation changes.
+     * @event conversationStateChange
+     * @see {@link on} for listener registration
+     */
+    static readonly CONVERSATION_STATE_CHANGE: 'conversationStateChange';
+    /**
+     * Event emitted when the {@link CallState} of this conversation changes.
+     * @event callStateChange
+     * @see {@link on} for listener registration
+     */
+    static readonly CALL_STATE_CHANGE: 'callStateChange';
+    /**
+     * Event emitted when the conversation ends.
+     * @deprecated The end event is not always available, depending on the configuration. Use the {@link CONVERSATION_STATE_CHANGE} event instead.
+     * @event end
+     * @see {@link on} for listener registration
+     */
+    static readonly END: 'end';
+    /**
+     * Event emitted when the conversation is closed.
+     *
+     * This may happen due to a UI-navigation or an API-call.
+     *
+     * @event close
+     * @see {@link on} for listener registration
+     */
+    static readonly CLOSE: 'close';
+    /**
+     * Event emitted when an {@link Invitation} is added to or removed from this conversation, or if an existing invitation changes.
+     * The event emits an array of all visitor invitations created by the local person, all other invitations will not be present.
+     * @event invitationsChange
+     * @see {@link on} for listener registration
+     */
+    static readonly INVITATIONS_CHANGE: 'invitationsChange';
+    /**
+     * Event emitted every time a custom action is configured to trigger a JS API event for the current client when a custom action is invoked
+     *
+     * @event customActionInvocation
+     * @see {@link CustomActionInvocationListener}
+     * @see {@link on} for listener registration
+     */
+    static readonly CUSTOM_ACTION_INVOCATION: 'customActionInvocation';
+    private eventEmitter;
+    private internalListeners;
+    private destroyed;
+    /**
+     * @hidden
+     */
+    constructor(conversationModule: ConversationModule, conversationId: string);
+    /**
+     * Registers an event listener for the given event.
+     * @param event The call state change event.
+     * @param listener The listener to be called.
+     * @see {@link CONNECTION_STATE_CHANGE}
+     */
+    on(event: typeof Conversation.CONNECTION_STATE_CHANGE, listener: ConnectionStateListener): void;
+    /**
+     * Registers an event listener for the given event.
+     * @param event The conversation state change event.
+     * @param listener The listener to be called.
+     * @see {@link CONVERSATION_STATE_CHANGE}
+     */
+    on(event: typeof Conversation.CONVERSATION_STATE_CHANGE, listener: ConversationStateListener): void;
+    /**
+     * Registers an event listener for the given event.
+     * @param event The call state change event.
+     * @param listener The listener to be called.
+     * @see {@link CALL_STATE_CHANGE}
+     */
+    on(event: typeof Conversation.CALL_STATE_CHANGE, listener: CallStateListener): void;
+    /**
+     * Registers an event listener for the given event.
+     * @deprecated The end event is not always available, depending on the configuration. Use instead {@link CONVERSATION_STATE_CHANGE} event.
+     * @param event The end event.
+     * @param listener The listener to be called.
+     * @see {@link END}
+     */
+    on(event: typeof Conversation.END, listener: () => void): void;
+    /**
+     * Registers an event listener for the given event.
+     * @param event The close event.
+     * @param listener The listener to be called.
+     * @see {@link CLOSE}
+     */
+    on(event: typeof Conversation.CLOSE, listener: () => void): void;
+    /**
+     * Registers an event listener for the given event.
+     * @param event The invitations change event.
+     * @param listener The listener to be called.
+     * @see {@link INVITATIONS_CHANGE}
+     */
+    on(event: typeof Conversation.INVITATIONS_CHANGE, listener: InvitationsListener): void;
+    /**
+     * Registers an event listener for the given event.
+     * @param event The customActionInvocation event.
+     * @param listener The listener to be called.
+     * @see {@link CUSTOM_ACTION_INVOCATION}
+     */
+    on(event: typeof Conversation.CUSTOM_ACTION_INVOCATION, listener: CustomActionInvocationListener): void;
+    /**
+     * Removes a previously registered listener.
+     * @param event The event to unregister from.
+     * @param listener The listener to remove.
+     */
+    off(event: ConversationEventType, listener: Listener): boolean;
+    private onInternal;
+    private offInternal;
+    /**
+     * Returns the ID of this conversation.
+     */
+    getConversationId(): string;
+    /**
+     * Returns the current connection state the conversation is in.
+     *
+     * If the connection is lost, the conversation will automatically try to reconnect using an exponential back-off strategy.
+     * If a fatal error is detected, the state will change to {@link ConnectionState.ERROR}.
+     *
+     * If this happens, the conversation is in it's terminal state. A dialog or other UI will be displayed to the user with details on the failure.
+     * The conversation is not automatically closed in this case.
+     * It may either be closed through a manual action by the visitor (confirming the error) or via the API.
+     *
+     * @see {@link CONNECTION_STATE_CHANGE} if you need to listen to changes.
+     * @return A promise that resolves to the current connection state of the conversation
+     * or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    getConnectionState(): Promise<ConnectionState>;
+    /**
+     * Returns the current state the conversation is in.
+     * @return A promise that resolves to the current state of the conversation
+     * or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    getConversationState(): Promise<ConversationState>;
+    /**
+     * @see {@link CALL_STATE_CHANGE} if you need to listen to changes.
+     * @return A promise that resolves to the current call state of the local user
+     * or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    getCallState(): Promise<CallState>;
+    /**
+     * Creates a new PIN invitation for this conversation.
+     *
+     * - If the local person doesn't have the right to invite a visitor,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.ACTION_NOT_GRANTED}.
+     * @see {@link INVITATIONS_CHANGE} if you need to listen to changes for new invitations on this conversation.
+     * @return A promise that resolves to a new {@link Invitation} object with all relevant metadata.
+     * or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    createAnonymousPinInvitation(): Promise<Invitation>;
+    /**
+     * Creates a new EMail invitation for this conversation.
+     *
+     * - If the local person doesn't have the right to invite a visitor,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.ACTION_NOT_GRANTED}.
+     * - If a non valid email address is provided,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.INVALID_FUNCTION_ARGUMENTS}.
+     * @param email The email which the invitation should be send. It must be a valid email address.
+     * @see {@link INVITATIONS_CHANGE} If you need to listen to changes for new invitations on this conversation.
+     * @return A promise that resolves to a new {@link Invitation} object with all relevant metadata.
+     * or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    createAnonymousEmailInvitation(email: String): Promise<Invitation>;
+    /**
+     * Revoke an invitation.
+     *
+     * - If the local person doesn't have the right to invite a visitor,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.ACTION_NOT_GRANTED}.
+     * @param invitationId The invitation id.
+     * @return A Promise that resolves to null or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    revokeInvitation(invitationId: String): Promise<void>;
+    /**
+     * Renews an invitation PIN if the invitation is expired.
+     *
+     * - If the local person doesn't have the right to invite a visitor,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.ACTION_NOT_GRANTED}.
+     * @param invitationId The invitation id.
+     * @return A promise that resolves to a new {@link Invitation} object with all relevant metadata.
+     */
+    renewInvitationPin(invitationId: String): Promise<Invitation>;
+    /**
+     * Set custom visitor data on the conversation.
+     *
+     * @param visitorData Custom data for the visitor in any format.
+     */
+    setVisitorData(visitorData: String): Promise<void>;
+    /**
+     * Get all visitor invitations created by the local person for this conversation.
+     * @return A promise that resolves to a new {@link Invitation} array with all relevant metadata.
+     * or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    getInvitations(): Promise<Invitation[]>;
+    /**
+     * Starts a voice call in this conversation.
+     *
+     * - If a call is already active, this call will be ignored.
+     * - If the local person doesn't have the right to start a voice call,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.ACTION_NOT_GRANTED}.
+     * @see {@link CALL_STATE_CHANGE} If you need to listen to changes.
+     * @return A Promise that resolves to null or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    startAudioCall(): Promise<void>;
+    /**
+     * Starts a video call in this conversation.
+     *
+     * - If a call is already active, this call will be ignored.
+     * - If the local person doesn't have the right to start a video call,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.ACTION_NOT_GRANTED}.
+     * @see {@link CALL_STATE_CHANGE} If you need to listen to changes.
+     * @return A Promise that resolves to null or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    startVideoCall(): Promise<void>;
+    /**
+     * Ends and closes this conversation.
+     *
+     * If the local person doesn't have the right to end the conversation,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.ACTION_NOT_GRANTED}.
+     * @see {@link END} fired after this call.
+     * @see {@link closeConversation} for details on closing a conversation.
+     * @return A Promise that resolves to null or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    endConversation(): Promise<void>;
+    /**
+     * Leaves and closes this conversation.
+     *
+     * By leaving, the visitor is removed from the active participant list of the conversation.
+     * Once a conversation is left, the visitor can not re-open it. It will not be visible in the conversation history either.
+     *
+     * If the local person doesn't have the right to leave the conversation,
+     * the returned promise will be rejected with the unblu error type {@link UnbluErrorType.ACTION_NOT_GRANTED}.
+     * @see {@link CLOSE} fired after this call.
+     * @see {@link closeConversation} for details on closing a conversation without leaving.
+     * @return A Promise that resolves to null or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    leaveConversation(): Promise<void>;
+    /**
+     * Closes this conversation locally.
+     *
+     * When called, the connection to this conversation is closed and the overview is displayed.
+     *
+     * **Note that:**
+     * - Closing does NOT end the conversation.
+     * - The person does NOT leave the conversation.
+     * - All Conversation api instances for this conversation will be destroyed.
+     *
+     * The conversation can be joined again either via the UI or using {@link UnbluApi.openConversation}.
+     * @see {@link CLOSE} fired after this call.
+     * @see {@link endConversation} for details on ending a conversation.
+     * @see {@link leavingConversation} for details on leaving a conversation.
+     * @see {@link destroy} for details on destroying a conversation.
+     * @return A Promise that resolves to null or is rejected with a {@link UnbluApiError} if the call fails.
+     */
+    closeConversation(): Promise<void>;
+    private checkNotDestroyed;
+    /**
+     * Returns weather this conversation is destroyed or not.
+     *
+     * Conversations are destroyed if {@link destroy} is called or the conversation is closed.
+     * This usually happens when the user navigates back to an overview or into an other conversation.
+     * @see {@link destroy}
+     * @see {@link CLOSE}
+     * @return Weather this conversation is destroyed or not.
+     */
+    isDestroyed(): boolean;
+    /**
+     * Destroys this conversation API instance.
+     *
+     * Calling destroy will unregister all event listeners and prohibit any further calls to this object.
+     * Once the conversation is destroyed, any subsequent calls will reject the returned promise with {@link UnbluErrorType.ILLEGAL_STATE} as the reason.
+     *
+     * **Note that:**
+     * - Destroying does NOT close the conversation .
+     * - Destroying does NOT end the conversation.
+     * - Destroying does NOT leave the conversation.
+     * - Other instances of the same Conversation will NOT be destroyed.
+     *
+     * This call simply destroys this local API instance to the conversation.
+     *
+     * A destroyed but still open conversation can be accessed again using {@link UnbluApi.getActiveConversation}.
+     *
+     * @see {@link isDestroyed}
+     * @see {@link closeConversation} for details on how to close a conversation
+     * @see {@link endConversation} for details on how to end a conversation
+     */
+    destroy(): void;
+}