src/app/services/feedback/FeedbackService.ts
//
// LESERKRITIKK v2 (aka Reader Critics)
// Copyright (C) 2017 DB Medialab/Aller Media AS, Oslo, Norway
// https://github.com/dbmedialab/reader-critics/
//
// This program is free software: you can redistribute it and/or modify it under
// the terms of the GNU General Public License as published by the Free Software
// Foundation, either version 3 of the License, or (at your option) any later
// version.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with
// this program. If not, see <http://www.gnu.org/licenses/>.
//
import Article from 'base/Article';
import EndUser from 'base/EndUser';
import Feedback from 'base/Feedback';
import FeedbackItem from 'base/FeedbackItem';
import FeedbackStatus from 'base/FeedbackStatus';
import User from 'base/User';
import Website from 'base/Website';
import BasicPersistingService from '../BasicPersistingService';
/**
* The feedback service stores feedbacks to articles and provides functions
* for several types of queries (TBD).
*
* Feedback objects do not yet have a unique constraint in the database, which
* means that it is theoretically possible to post the exact same object more
* than once.
*
* Feedback objects are never updated completely, only separate fields will be
* writeable (for example, when changing the queue status). Therefore this
* service does not have a generic update() function.
*/
interface FeedbackService extends BasicPersistingService <Feedback> {
/**
* Returns amount of feedbacks exist for current article
* @throws EmptyError
*/
getAmountByArticle(
article : Article
) : Promise <number>;
/**
* Get all feedback objects related to one article.
* @throws EmptyError
*/
getByArticle(
article : Article,
skip? : number,
limit? : number,
sort? : Object
) : Promise <Feedback[]>;
/**
* Get all feedback objects related to one article author, optionally filter
* also by website.
* @throws EmptyError
*/
getByArticleAuthor(
author : User,
website? : Website,
skip? : number,
limit? : number,
sort? : Object
) : Promise <Feedback[]>;
/**
* Get a single feedback object, identified by its database ID
* @throws EmptyError
*/
getByID(objectID : string, populated? : boolean) : Promise <Feedback>;
/**
* Get all feedbacks with a specific status, with additional query object
*/
getByStatus(
currentStatus : FeedbackStatus,
additionalQuery? : {},
skip? : number,
limit? : number,
sort? : Object
) : Promise <Feedback[]>;
/**
* Get a feedback object by its one-shot update token
*/
getByUpdateToken(oneshotUpdateToken : string) : Promise <Feedback>;
/**
* Save the new feedback object and create references to all involved objects.
* The references to the Website and User objects are copied over from the
* provided Article object. This is needed for complex querying with filters.
* The array of Users equals the article's authors.
*
* @throws EmptyError If one of the mandatory parameters is missing.
*/
save(
article : Article,
user : EndUser,
items : FeedbackItem[],
status? : FeedbackStatus,
oneshotUpdateToken? : string
) : Promise <Feedback>;
/**
* Takes a raw input object and validates its structure before saving the
* contained feedback with all references. This function uses save() as soon
* as all involved objects have been fetched for referencing, of course under
* the condition that the initial validation does not throw an error.
*
* This function is intended for usage on the API, so that the data does not
* have to be validated there. Just receive the data from the
*
* After validating, the function internally fetches the article that this
* feedback is based on (identified by its key properties "url" and "version")
* and in a parallel database action, retrieves or (if not existing) creates
* the EndUser object of Anonymous user.
*
* When these two objects (Article and EndUser) are ready, both are given to
* save() together with the feedback items, which are also parsed from the raw
* input object.
*
* TODO: real JSON schema validation, linking the schema file here in the
* documentation for reference. See RC-110.
*
* @throws SchemaValidationError If the input data does not pass validation
*/
validateAndSave(data : {}) : Promise <Feedback>;
/**
* Takes another raw input object from the API, validates its structure, then
* checks the update-token and on success, updates the enduser data ob the
* Feedback object in the database.
*/
validateAndUpdateEnduser(data : {}) : Promise <Feedback>;
/**
* Updates the existing feedback object with enduser data.
* @throws EmptyError If enduser parameter is missing.
*/
updateEndUser(
feedback : Feedback,
enduser : EndUser
) : Promise <Feedback>;
/**
* Updates the current status of the feedback object and puts the (now)
* previous status into the log array.
*/
updateStatus(
feedback : Feedback,
newStatus : FeedbackStatus
) : Promise <void>
}
export default FeedbackService;