/*
 * Copyright 2019 New Vector Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package im.vector.matrix.android.api.session.room.model.relation

import androidx.lifecycle.LiveData
import im.vector.matrix.android.api.MatrixCallback
import im.vector.matrix.android.api.session.events.model.Event
import im.vector.matrix.android.api.session.room.model.EventAnnotationsSummary
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
import im.vector.matrix.android.api.util.Cancelable
import im.vector.matrix.android.api.util.Optional

/**
 * In some cases, events may wish to reference other events.
 * This could be to form a thread of messages for the user to follow along with,
 * or to provide more context as to what a particular event is describing.
 * Relation are used to associate new information with an existing event.
 *
 * Relations are events which have an m.relates_to mixin in their contents,
 * and the new information they convey is expressed in their usual event type and content.
 *
 * Three types of relations are defined, each defining different behaviour when aggregated:
 *
 *  m.annotation - lets you define an event which annotates an existing event.
 *                  When aggregated, groups events together based on key and returns a count.
 *                  (aka SQL's COUNT) These are primarily intended for handling reactions.
 *
 *  m.replace - lets you define an event which replaces an existing event.
 *             When aggregated, returns the most recent replacement event. (aka SQL's MAX)
 *             These are primarily intended for handling edits.
 *
 *  m.reference - lets you define an event which references an existing event.
 *              When aggregated, currently doesn't do anything special, but in future could bundle chains of references (i.e. threads).
 *              These are primarily intended for handling replies (and in future threads).
 */
interface RelationService {

    /**
     * Sends a reaction (emoji) to the targetedEvent.
     * It has no effect if the user has already added the same reaction to the event.
     * @param targetEventId the id of the event being reacted
     * @param reaction the reaction (preferably emoji)
     */
    fun sendReaction(targetEventId: String,
                     reaction: String): Cancelable

    /**
     * Undo a reaction (emoji) to the targetedEvent.
     * @param targetEventId the id of the event being reacted
     * @param reaction the reaction (preferably emoji)
     */
    fun undoReaction(targetEventId: String,
                     reaction: String): Cancelable

    /**
     * Edit a text message body. Limited to "m.text" contentType
     * @param targetEventId The event to edit
     * @param newBodyText The edited body
     * @param compatibilityBodyText The text that will appear on clients that don't support yet edition
     */
    fun editTextMessage(targetEventId: String,
                        msgType: String,
                        newBodyText: CharSequence,
                        newBodyAutoMarkdown: Boolean,
                        compatibilityBodyText: String = "* $newBodyText"): Cancelable

    /**
     * Edit a reply. This is a special case because replies contains fallback text as a prefix.
     * This method will take the new body (stripped from fallbacks) and re-add them before sending.
     * @param replyToEdit The event to edit
     * @param originalTimelineEvent the message that this reply (being edited) is relating to
     * @param newBodyText The edited body (stripped from in reply to content)
     * @param compatibilityBodyText The text that will appear on clients that don't support yet edition
     */
    fun editReply(replyToEdit: TimelineEvent,
                  originalTimelineEvent: TimelineEvent,
                  newBodyText: String,
                  compatibilityBodyText: String = "* $newBodyText"): Cancelable

    /**
     * Get the edit history of the given event
     */
    fun fetchEditHistory(eventId: String, callback: MatrixCallback<List<Event>>)

    /**
     * Reply to an event in the timeline (must be in same room)
     * https://matrix.org/docs/spec/client_server/r0.4.0.html#id350
     * The replyText can be a Spannable and contains special spans (MatrixItemSpan) that will be translated
     * by the sdk into pills.
     * @param eventReplied the event referenced by the reply
     * @param replyText the reply text
     * @param autoMarkdown If true, the SDK will generate a formatted HTML message from the body text if markdown syntax is present
     */
    fun replyToMessage(eventReplied: TimelineEvent,
                       replyText: CharSequence,
                       autoMarkdown: Boolean = false): Cancelable?

    /**
     * Get the current EventAnnotationsSummary
     * @param eventId the eventId to look for EventAnnotationsSummary
     * @return the EventAnnotationsSummary found
     */
    fun getEventAnnotationsSummary(eventId: String): EventAnnotationsSummary?

    /**
     * Get a LiveData of EventAnnotationsSummary for the specified eventId
     * @param eventId the eventId to look for EventAnnotationsSummary
     * @return the LiveData of EventAnnotationsSummary
     */
    fun getEventAnnotationsSummaryLive(eventId: String): LiveData<Optional<EventAnnotationsSummary>>
}
