# Actions Service Interface

/**
 * JSON resonse with a status code of !=200:
 * {
 *     success: false;
 *     message: string;
 * }
 *
 */
Exception ActionException(message: string);

/**
 * Executes multiple actions in the context of the user given by the user_id.
 * All actions are depdend: If one fails, nothing is written to the DataStore.
 * It can be seen as one transaction.
 *
 * For each action an ActionResult is returned. If an action has an error,
 * ActionError is used in combination wuth error_index to indicate, which action
 * resulted in an error.
 *
 * For general, non specific action-related, errors an ActionException is used.
 *
 * @throws ActionException
 */
handle_request (payload: Action[], user_id: Id): ActionsResponse | ActionError

interface Action {
    action: string;
    data: object[];  # An array of action specific data.
}

interace ActionsResponse {
    success: true;
    message: string;

    /**
     * this is a potentially double-array with entries for each action
     * and, if not null, an array for each data provided for each action.
     *
     *
     * If an action does not producy a result, the inner array can be omitted and
     * null can be used. If the inner array is given, each entry must be an object
     * with the result (e.g. for a create action `{id: <the id>}`) or null.

     * E.g. for valid arrays (two actions with two data entries each):
     * - [null, null]
     * - [null, [null, null]]
     * - [null, [{id: 2}, null]]
     * - [[{id: 2}, {id: 3}], [{id: 5}, {id: 8}]]
     **/
    results: ((object | null)[] | null )[]
}

interface ActionError {
    success: false;
    message: string;
    error_index: number;
}