//
//  BWFCallCenter.h
//  BWFCallCenterFramework
//
//  Copyright © 2019 Beowulf. All rights reserved.
//

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>


#import "BWFRequestEntity.h"

NS_ASSUME_NONNULL_BEGIN

/*!
 @abstract A block instance to rate a call quality or call center service
 @param satisfyFraction : a fraction evaluates the level of satisfaction of customer
        comment: comment of customer
        resultBlock: result of rating
 @discussion + 'satisfyFraction' must be between 0 and 1.
             + Assign to 'satisfyFraction' a negative value will result to 0
             + Assign to 'satisfyFraction' a greater-than-one value will result to 1

             + Result of rating will return in resultBlock indicating rating is successful or not
 */
typedef void(^RatingCompletionHandler)(CGFloat satisfyFraction, NSString * _Nullable comment, void(^resultBlock)(BOOL));



@protocol BWFCallCenterProtocol;
@protocol BWFCallCenterForRequesterProtocol;
@interface BWFCallCenter : NSObject


/*!
 @abstract THE MOST IMPORTANT METHOD
 @param apiKey : a valid apiKey
 @discussion Call this method before doing any actions of this framework
             If this method is not call, the framework can't be used
             Please go to 'https://beowulfchain.com/login', login or register an account then create an API key
 */
+ (BOOL)configureWithApiKey:(NSString *)apiKey;


/*!
 @abstract Delegate to receive callback for result or error
 @param callcenterDelegate : object that will receive result or error for common actions
        callcenterForRequesterDelegate: object that will receive result or error for actions from requesters
 @discussion + Set the delegates before calling other methods to receive result or error
             + Must call after `+configureWithApiKey:`
 */
+ (void)setCallCenterDelegate:(id<BWFCallCenterProtocol>)callcenterDelegate;
+ (void)setCallCenterForRequesterDelegate:(id<BWFCallCenterForRequesterProtocol>)callcenterForRequesterDelegate;


/*!
 @abstract Start the framework
 @discussion This is an asynchronous method and takes a while to finish
    - As the name of itself, framework will be started with an anonymous identity.
    - If framework starts successfully, following method of protocol `BWFCallCenterProtocol` will be invoked
        ============================================================================================
        = - (void)bwfCallCenterDidStartAsRequesterWithIdentifier:(NSString * _Nullable)identifier; =
        ============================================================================================
         + Parameters:
             |Field|Type|Description|
             |----------|------------|------------|
             |`identifier`|`NSString`|an identifier of the anonymous account|
         + Notes: `identifier` will be `nil` in this case because of starting as anonymous.
 
    - If framework failed to start, following method of protocol `BWFCallCenterProtocol` will be invoked
        =====================================================================
        = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error; =
        =====================================================================
         + Notes: Possible error codes: 10, 20, 21, 22, 23, 24
 
 @see For more detail, check
         + File 'BWFErrorDefine.h'
         + Protocol 'BWFCallCenterProtocol'
         + Class 'BWFCallCenterError'
 */
+ (void)startAsAnonymousRequester;

/*!
 @abstract Stop the framework
 @discussion Stop the framework.
    - Once the framework is stopped, any action won't be operated. Call starting-framework method to start framework again
 
    - Implement protocol `BWFCallCenterProtocol` to receive error if it occurs
        =====================================================================
        = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error; =
        =====================================================================
         + Possible error: 10, 11
 @see For more detail, check
         + File 'BWFErrorDefine.h'
         + Protocol 'BWFCallCenterProtocol'
         + Class 'BWFCallCenterError'
 */
+ (void)stop;


/*!
 @abstract End current connected or outgoing request
 @discussion Errors may be returned in case failure via following method of protocol `BWFCallCenterProtocol`
         =====================================================================
         = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error  =
         =====================================================================
             + Possible errors: 10, 11
 @see For more detail, check
     + File 'BWFErrorDefine.h'
     + Protocol 'BWFCallCenterProtocol'
     + Class 'BWFCallCenterError'
 */
+ (void)endSupporting;


/*!
 @abstract Get duration of current call at the moment
 @discussion Get current duration of active call
    - Errors may be returned in case failure via following method of protocol `BWFCallCenterProtocol`
        =====================================================================
        = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error  =
        =====================================================================
            + Possible errors: 10, 11
 @see For more detail, check
     + File 'BWFErrorDefine.h'
     + Protocol 'BWFCallCenterProtocol'
     + Class 'BWFCallCenterError'
 */
+ (NSInteger)durationOfCurrentCall;


/*!
 @abstract Checking whether is in any connected voice/video call or not
 @discussion This method will indicate that app currently whether is in any connected voice/video call or not
    - Errors may be returned in case failure via following method of protocol `BWFCallCenterProtocol`
        =====================================================================
        = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error  =
        =====================================================================
            + Possible errors: 10, 11
 @see For more detail, check
     + File 'BWFErrorDefine.h'
     + Protocol 'BWFCallCenterProtocol'
     + Class 'BWFCallCenterError'
 */
+ (BOOL)isInAnyCallNow;


/*!
 @abstract Send text message
 @param text : a text message sent to the receiver
        identifier: an identifier of the supporter
        resultBlock: a result block that returns a messageId (an unique identifier of the message) and an error code used to figure out which error occurs
        messageId: an unique identifier of the message
 @discussion Param `messageId` can be nil in case unable to send message
    - Errors may be returned in case failure via following method of protocol `BWFCallCenterProtocol`
         =====================================================================
         = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error  =
         =====================================================================
            + Possible errors: 10, 11, 23, 202, 203
 @see For more detail, check
     + File 'BWFErrorDefine.h'
     + Protocol 'BWFCallCenterProtocol'
     + Class 'BWFCallCenterError'
 */
+ (void)sendText:(NSString *)text
    toIdentifier:(NSString *)identifier
     resultBlock:(void(^)(NSString* _Nullable messageId))resultBlock;


/*!
 @abstract Send image message
 @param url : an url to where an image is uploaded. It will be sent to the receiver
        identifier: an identifier of the supporter
        resultBlock: a result block that returns a messageId (an unique identifier of the message) and an error code used to figure out which error occurs
        messageId: an unique identifier of the message
 @discussion Param `messageId` can be nil in case unable to send message
    - Errors may be returned in case failure via following method of protocol `BWFCallCenterProtocol`
         =====================================================================
         = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error  =
         =====================================================================
            + Possible errors: 10, 11, 23, 202, 203
 @see For more detail, check
     + File 'BWFErrorDefine.h'
     + Protocol 'BWFCallCenterProtocol'
     + Class 'BWFCallCenterError'
 */
+ (void)sendImage:(NSString *)url
     toIdentifier:(NSString *)identifier
      resultBlock:(void(^)(NSString* _Nullable messageId))resultBlock;


/*!
 @abstract Send seen status
 @param messageId: an unique identifier of the message
        identifier: an unique id to identify an user on your platform. In this case, it's an identifier of whom the Seen status will be notify to
 @discussion - Usecase:
                + A sends a message to B
                + B receives the message
                + B read the message
                + Seen status will be sent to A
                - Check section (# Receive message status) to know how to catch Seen status
    - Errors may be returned in case failure via following method of protocol `BWFCallCenterProtocol`
         =====================================================================
         = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error  =
         =====================================================================
            + Possible errors: 10, 11, 204
 @see For more detail, check
     + File 'BWFErrorDefine.h'
     + Protocol 'BWFCallCenterProtocol'
     + Class 'BWFCallCenterError'
 */
+ (void)sendSeenStatusForMessageId:(NSString *)messageId
                      toIdentifier:(NSString *)identifier;


@end


@interface BWFCallCenter (Requester)

/*!
 @abstract Request Voice-call support
 @param name: display name which will be shown on receiver's incoming screens to help the receiver knows who the requester is
        groupName: the name of the group of supporters to be requested. The name of group should be exactly correct and case sensitive
 @discussion + Implement methods of protocol `BWFCallCenterProtocol` and `BWFCallCenterForRequesterProtocol` to receive result or catch error
    + If an supporter is available, it'll be returned in this method of protocol `BWFCallCenterForRequesterProtocol`
         =========================================================================================
         = - (void)bwfCallCenterDidFindSupporterViaRequest:(BWFRequestEntity * _Nonnull)request; =
         =========================================================================================
             + Parameters:
             |Field|Type|Description|
             |----------|------------|------------|
             |`request`|`BWFRequestEntity`|the request object that obtains information about the request and result of the request. In this case, the property `toIdentifier` is the identity of the found supporter. The value of property `toIdentifier` should be stored for further usage (for example: sending message)|
 
    + Errors may be returned in case failure via following method of protocol `BWFCallCenterProtocol`
         =====================================================================
         = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error  =
         =====================================================================
            + Possible errors: 10, 11, 26, 100, 326
 @see For more detail, check
     + Class `BWFRequestEntity.h`
     + File 'BWFErrorDefine.h'
     + Protocol 'BWFCallCenterProtocol'
     + Class 'BWFCallCenterError'
 */
+ (void)requestVoiceCallWithDisplayName:(NSString * _Nullable)name
                                toGroup:(NSString * _Nonnull)groupName;



/*!
 @abstract Request Chat support
 @param name: display name which will be shown on receiver's incoming screens to help the receiver knows who the requester is
 groupName: the name of the group of supporters to be requested. The name of group should be exactly correct and case sensitive
 @discussion + Implement methods of protocol `BWFCallCenterProtocol` and `BWFCallCenterForRequesterProtocol` to receive result or catch error
     + If an supporter is available, it'll be returned in this method of protocol `BWFCallCenterForRequesterProtocol`
         =========================================================================================
         = - (void)bwfCallCenterDidFindSupporterViaRequest:(BWFRequestEntity * _Nonnull)request; =
         =========================================================================================
             + Parameters:
             |Field|Type|Description|
             |----------|------------|------------|
             |`request`|`BWFRequestEntity`|the request object that obtains information about the request and result of the request. In this case, the property `toIdentifier` is the identity of the found supporter. The value of property `toIdentifier` should be stored for further usage (for example: sending message)|
    + After that, take the `toIdentifier` to send text message or image messages by calling following methods
         =========================================================================================
         = + (void)sendText:(NSString *)text                                                     =
         =      toIdentifier:(NSString *)identifier                                              =
         =       resultBlock:(void(^)(NSString* _Nullable messageId))resultBlock;                =
         =                                                                                       =
         = + (void)sendImage:(NSString *)url                                                     =
         =      toIdentifier:(NSString *)identifier                                              =
         =       resultBlock:(void(^)(NSString* _Nullable messageId))resultBlock;                =
         =========================================================================================
 
    + Errors may be returned in case failure via following method of protocol `BWFCallCenterProtocol`
         =====================================================================
         = - (void)bwfCallCenterFailedWithError:(BWFCallCenterError *)error  =
         =====================================================================
            + Possible errors: 10, 11, 26, 100, 326
 @see For more detail, check
     + Class `BWFRequestEntity.h`
     + File 'BWFErrorDefine.h'
     + Protocol 'BWFCallCenterProtocol'
     + Class 'BWFCallCenterError'
 */
+ (void)requestChatWithDisplayName:(NSString * _Nullable)name
                           toGroup:(NSString * _Nonnull)groupName;

@end

NS_ASSUME_NONNULL_END
