package query.hessian.accounts;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.io.Serializable;

/**
 * Account-related operations via GameTool.
 * API provides access to avatars of account.
 * Item actions can be performed and queried for avatars.
 *
 * @author andrey.kuprishov
 */
public interface AccountService extends Serializable {
  /**
   * Get all shards known to GameTool (both online and offline shards).
   *
   * @throws AccountServiceException when internal GameTool error occures (e.g. DB unavailable).
   */
  @NotNull
  String[] getAllShards() throws AccountServiceException;

  /**
   * Get all avatars of account.
   * Even deleted avatars will be returned. Shard of avatar is specified in AvatarOnShard.
   *
   * @see AvatarOnShard
   * @throws AccountServiceException when internal GameTool error occures (e.g. DB unavailable).
   */
  @NotNull
  AvatarOnShard[] getAvatars(@NotNull String account) throws AccountServiceException;

  /**
   * Give item to specified avatar. GameTool creates action and tries to perform action periodically.
   * Item will be given only when shard of avatar is online.
   *
   * @param shard shard of avatar.
   * @param avatarId  id of avatar on shard.
   * @param itemResourceId  item resource id.
   * @param runeResourceId  rune resource id (0 if no rune needed).
   * @param stackCount  stack count for stackable items, 1 for unstackable items.
   * @param counter counter for items with counters, -1 if item doesn't support counter.
   * @return  result of giving item, contains status (succeeded, shard can be not found, avatar can be not found, etc.)
   *          and newly created action id to query this action via other api methods.
   *
   * @see GiveItemStatus
   * @see GiveItemResult
   * @throws AccountServiceException when internal GameTool error occures (e.g. DB unavailable).
   */
  @NotNull
  GiveItemResult giveItemToAvatar(@NotNull String shard, long avatarId, int itemResourceId, int runeResourceId, int stackCount, int counter) throws AccountServiceException;

  /**
   * Gets action information about previously given item.
   *
   * @param itemActionId  id of action that was in GiveItemResult returned by giveItemToAvatar.
   * @return information about item action, or null if action not found
   * @see ItemActionInfo
   * @throws AccountServiceException when internal GameTool error occures (e.g. DB unavailable).
   */
  @Nullable
  ItemActionInfo getGivenAvatarItem(long itemActionId) throws AccountServiceException;

  /**
   * Gets information about all previously given items to avatar at specified shard.
   *
   * @param shard name of shard where avatar leaves.
   * @param avatarId  id of avatar on shard.
   * @return  information about items as array of action information.
   * @throws AccountServiceException when internal GameTool error occures (e.g. DB unavailable).
   * @see ItemActionInfo
   */
  @NotNull
  ItemActionInfo[] getGivenAvatarItems(@NotNull String shard, long avatarId) throws AccountServiceException;

  /**
   * Cancels pending action that was created to give item to avatar.
   * Useful if for example shard is too long in offline mode (hours/days), and item can be given to another avatar
   * on another shard.
   * Failes when action is not pending (e.g. already performed).
   *
   * @param itemActionId  id of action that was returned from giveItemToAvatar.
   * @return  result of cancellation: cancelled, or action not found, or action is not pending).
   * @throws AccountServiceException when internal GameTool error occures (e.g. DB unavailable).
   * @see CancelItemResult
   */
  @NotNull
  CancelItemResult cancelPendingAvatarItem(long itemActionId) throws AccountServiceException;
}