using System.Collections.Generic;
using TS.Insightly.API.Contract;

namespace TS.Insightly.API.Interface
{
    /// <summary>
    /// Insightly API access.
    /// </summary>
    public interface IApi
    {
        #region Contacts

        /// <summary>
        /// Gets the contact for the unique contact ID.
        /// Note that the Id is not the Id shown for the contact in the web browser, but
        /// the contact Id that is unique to insightly.
        /// </summary>
        /// <param name="contactId">The contact unique identifier.</param>
        /// <returns>The contact for the given id.</returns>
        Contact GetContact(int contactId);

        /// <summary>
        /// Gets the contacts for email address.
        /// </summary>
        /// <param name="emailAddress">The email address.</param>
        /// <returns>List of contacts with a matching email address or empty list if no matches found.</returns>
        List<Contact> GetContactsForEmail(string emailAddress);

        /// <summary>
        /// Adds the new contact.
        /// </summary>
        /// <param name="newContact">The new contact.</param>
        /// <returns>The added contact if successful.</returns>
        Contact AddNewContact(Contact newContact);

        /// <summary>
        /// Adds the new contact if a contact does not already exist for the same email, 
        /// first and last names as the given contact.
        /// </summary>
        /// <param name="newContact">The new contact.</param>
        /// <returns>Structure containing details of the add.</returns>
        InsightlyAPI.ContactAddResult AddNewContactIfNotExists(Contact newContact);

        /// <summary>
        /// Deletes the contact.
        /// Note that the Id is not the Id shown for the contact in the web browser, but
        /// the contact Id that is unique to insightly.
        /// </summary>
        /// <param name="contactId">The contact unique identifier.</param>
        /// <returns><code>true</code> If the contact was deleted.</returns>
        bool DeleteContact(int contactId);

        #endregion Contacts

        #region Organisations

        /// <summary>
        /// Gets the organisation for the unique organisation ID.
        /// Note that the Id is not the Id shown for the organisation in the web browser, but
        /// the organisation Id that is unique to insightly.
        /// </summary>
        /// <param name="organisationId">The organisation unique identifier.</param>
        /// <returns>The organisation for the given id.</returns>
        Organisation GetOrganisation(int organisationId);

        /// <summary>
        /// Gets organisations.
        /// </summary>
        /// <param name="fullDetails">if set to <c>true</c> return full details.</param>
        /// <returns>All organisations.</returns>
        List<Organisation> GetOrganisations(bool fullDetails);

        /// <summary>
        /// Gets organisations matching the given name.
        /// </summary>
        /// <param name="orgName">Name of the org to find.</param>
        /// <returns>List of organisations (basic details) matching the given name.</returns>
        List<Organisation> GetOrganisationsForName(string orgName);

        /// <summary>
        /// Adds the new organisation.
        /// </summary>
        /// <param name="newOrganisation">The new organisation.</param>
        /// <returns>The added organisation if successful.</returns>
        Organisation AddNewOrganisation(Organisation newOrganisation);

        /// <summary>
        /// Deletes the organisation.
        /// Note that the Id is not the Id shown for the organisation in the web browser, but
        /// the organisation Id that is unique to insightly.
        /// </summary>
        /// <param name="organisationId">The organisation unique identifier.</param>
        /// <returns><code>true</code> If the organisation was deleted.</returns>
        bool DeleteOrganisation(int organisationId);

        #endregion Organisations

        #region Projects

        /// <summary>
        /// Gets the project for the unique organisation ID.
        /// Note that the Id is not the Id shown for the project in the web browser, but
        /// the project Id that is unique to insightly.
        /// </summary>
        /// <param name="projectId">The project unique identifier.</param>
        /// <returns>The project for the given id.</returns>
        Project GetProject(int projectId);

        /// <summary>
        /// Gets projects.
        /// </summary>
        /// <param name="fullDetails">if set to <c>true</c> return full details.</param>
        /// <returns>All projects.</returns>
        List<Project> GetProjects(bool fullDetails);

        #endregion Projects

    }
}