Source

vendors/AWS/tmaApi.js

  1. // File imports
  2. import axios from "axios";
  4. /**
  5.  * The server API for the app
  6.  * @module tmaApi
  7.  * @category Server
  8.  * @author Dan Levy <danlevy124@gmail.com>
  9.  * @author Daniel Griessler <dgriessler20@gmail.com>
  10.  */
  12. // Sets the base URL for the server
  13. axios.defaults.baseURL = process.env.REACT_APP_SERVER_BASE_URL;
  15. /**
  16.  * Sets the Axios auth token.
  17.  * The auth token only needs to be set when auth changes.
  18.  * @function
  19.  * @param {string} authToken - The auth token to use for API requests
  20.  */
  21. export const setAxiosAuthToken = (authToken) => {
  22.     axios.defaults.headers.common["Authorization"] = authToken;
  23. };
  25. /**
  26.  * A server error
  27.  * @typedef {object} ServerError
  28.  * @property {object} response - The error response
  29.  * @property {string} response.status - The error status code
  30.  * @property {object} response.data - The error data (usually just a string)
  31.  */
  33. /**
  34.  * A user from the server
  35.  * @typedef {object} User
  36.  * @property {object} data - The response data
  37.  * @property {string} data.firstName - The user's first name
  38.  * @property {string} data.lastName - The user's last name
  39.  * @property {boolean} data.hasPicture - Indicates if the user has a profile picture
  40.  */
  42. /**
  43.  * Gets the user
  44.  * @function
  45.  * @returns {Promise<module:tmaApi~User|module:tmaApi~ServerError>} A promise containing the user or an error
  46.  */
  47. export const getUser = () => {
  48.     return axios.get("/person");
  49. };
  51. /**
  52.  * Adds a user to the database
  53.  * @function
  54.  * @param {module:tmaApi~User} data - User data
  55.  * @returns {Promise<null|ServerError>} A promise containing nothing on success or an error
  56.  */
  57. export const addUser = (data) => {
  58.     return axios.post("/person", data);
  59. };
  61. /**
  62.  * Updates a user in the database
  63.  * @function
  64.  * @param {module:tmaApi~User} data - User data
  65.  * @returns {Promise<null|module:tmaApi~ServerError>} A promise containing nothing on success or an error
  66.  */
  67. export const updateUser = (data) => {
  68.     return axios.put("/person", data);
  69. };
  71. /**
  72.  * The choir access code
  73.  * @typedef {object} ChoirAccess
  74.  * @property {string} accessCode - The access code of the generated choir
  75.  */
  77. /**
  78.  * Adds a choir to the database
  79.  * @function
  80.  * @param {object} data - Choir data
  81.  * @param {string} data.choirName - The name of the choir
  82.  * @param {string} data.description - A description of the choir
  83.  * @param {string} data.memberType - The member type of the member creating the choir
  84.  * @param {string} data.memberRole - The member role of the member creating the choir
  85.  * @returns {Promise<module:tmaApi~ChoirAccess|module:tmaApi~ServerError>} A promise containing the access code of the generated choir or an error
  86.  */
  87. export const addChoir = (data) => {
  88.     return axios.post("/choir", data);
  89. };
  91. /**
  92.  * A list of choirs
  93.  * @typedef {object} ChoirList
  94.  * @property {object} data - Choir list data
  95.  * @property {module:tmaApi~Choir[]} data.choirs - Choir list
  96.  */
  98. /**
  99.  * A choir
  100.  * @typedef {object} Choir
  101.  * @property {string} choir_id - The ID of the choir
  102.  * @property {string} choir_name - The name of the choir
  103.  * @property {string} description - A description of the choir
  104.  */
  106. /**
  107.  * Gets the choirs that the current user is a part of
  108.  * @function
  109.  * @returns {Promise<module:tmaApi~ChoirList|module:tmaApi~ServerError>} A promise containing choir information or an error
  110.  */
  111. export const getUsersChoirs = () => {
  112.     return axios.get("/choir");
  113. };
  115. /**
  116.  * A list of choir members
  117.  * @typedef {object} MemberList
  118.  * @property {module:tmaApi~ChoirMember[]} data - Choir member list
  119.  */
  121. /**
  122.  * A choir member
  123.  * @typedef {object} ChoirMember
  124.  * @property {string} first_name The first name of the member
  125.  * @property {string} last_name The last name of the member
  126.  * @property {string} member_role The role of the member
  127.  * @property {string} person_id The ID of the person attached to the member
  128.  * @property {boolean} has_picture Whether the given member is attached to a person with a profile picture or not
  129.  */
  131. /**
  132.  * Gets the given choir members
  133.  * @function
  134.  * @param {object} data - Choir data
  135.  * @param {string} data.choirId - The ID of the choir to receive members of
  136.  * @returns {Promise<module:tmaApi~MemberList|module:tmaApi~ServerError>} - A promise containing members or an error
  137.  */
  138. export const getChoirMembers = (data) => {
  139.     return axios.request({
  140.         method: "GET",
  141.         url: "/choir/members",
  142.         params: data,
  143.     });
  144. };
  146. /**
  147.  * Accepts a given choir member into the given choir
  148.  * @function
  149.  * @param {object} data - Member data
  150.  * @param {object} data.memberId - The ID of the member to accept
  151.  * @param {string} data.choirId - The choir ID of the choir that the user should be accepted into
  152.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  153.  */
  154. export const acceptChoirMember = (data) => {
  155.     return axios.put("/member/accept", data);
  156. };
  158. /**
  159.  * Rejects a given choir member from entering the given choir
  160.  * @function
  161.  * @param {object} data - Member data
  162.  * @param {object} data.memberId - The ID of the member to reject
  163.  * @param {string} data.choirId - The choir ID of the choir that the user should be rejected from
  164.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  165.  */
  166. export const rejectChoirMember = (data) => {
  167.     return axios.put("/member/reject", data);
  168. };
  170. /**
  171.  * A list of choir members.
  172.  * This array contains more member data than the {@link module:tmaApi~MemberList}.
  173.  * @typedef MemberListExtended
  174.  * @property {module:tmaApi~ChoirMemberExtended[]} data - Choir member list
  175.  */
  177. /**
  178.  * A choir member.
  179.  * This object contains more member data than the {@link module:tmaApi~ChoirMember}.
  180.  * @typedef {object} ChoirMemberExtended
  181.  * @property {string} member_id - The ID of the member
  182.  * @property {string} first_name - The first name of the member
  183.  * @property {string} email - The email of the member
  184.  * @property {string} member_type - The type of the member
  185.  * @property {string} member_role - The role of the member
  186.  * @property {boolean} has_picture - Indicates if the member has a profile picture
  187.  */
  189. /**
  190.  * Gets pending members of the given choir
  191.  * @function
  192.  * @param {object} data - Choir data
  193.  * @param {string} data.choirId - The ID of the choir to get pending members from
  194.  * @returns {Promise<module:tmaApi~MemberListExtended|module:tmaApi~ServerError>} - A promise containing pending members or an error
  195.  */
  196. export const getPendingMembers = (data) => {
  197.     return axios.request({
  198.         method: "GET",
  199.         url: "/member/pending",
  200.         params: data,
  201.     });
  202. };
  204. /**
  205.  * @typedef {object} GetsFeedback
  206.  * @property {object} data - Response data
  207.  * @property {boolean} gets_feedback Indicates if the user gets feedback (i.e. real-time feedback and performance data)
  208.  */
  210. /**
  211.  * Gets if the user recieves feedback
  212.  * @function
  213.  * @param {Object} data - Sheet music data
  214.  * @param {string} data.sheetMusicId - The id of the sheet music the user is singing
  215.  * @returns {Promise<module:tmaApi~GetsFeedback|module:tmaApi~ServerError>} - A promise containing whether the user gets feedback or an error
  216.  */
  217. export const doesUserGetFeedback = (data) => {
  218.     return axios.request({
  219.         method: "GET",
  220.         url: `/member/gets-feedback`,
  221.         params: data,
  222.     });
  223. };
  225. /**
  226.  * Adds the user as a pending member of the given choir
  227.  * @function
  228.  * @param {object} data - Member and choir data
  229.  * @param {string} data.memberType - The member type that you are attempting to join as
  230.  * @param {string} data.memberRole - The member role that you are attempting to join as
  231.  * @param {string} data.accessCode - The access code for the choir you are attempting to join
  232.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  233.  */
  234. export const joinChoir = (data) => {
  235.     return axios.post("/member", data);
  236. };
  238. /**
  239.  * @typedef {object} SheetMusicInfoList
  240.  * @property data - Sheet music data
  241.  * @property {module:tmaApi~SheetMusicInfo[]} sheet_music - An array of sheet music info
  242.  */
  244. /**
  245.  * @typedef {object} SheetMusicInfo
  246.  * @property {string} sheet_music_id - The ID of the sheet music
  247.  * @property {string} title - The title of the sheet music
  248.  * @property {string} composer_names - The names of the composers
  249.  */
  251. /**
  252.  * Gets all sheet music for a choir
  253.  * @function
  254.  * @param data - Choir data
  255.  * @param {string} data.choirId - The id of the choir to get sheet music info for
  256.  * @returns {Promise<module:tmaApi~SheetMusicInfoList|module:tmaApi~ServerError>} - A promise containing sheet music info or an error
  257.  */
  258. export const getSheetMusic = (data) => {
  259.     return axios.request({
  260.         method: "GET",
  261.         url: `/sheet-music`,
  262.         params: data,
  263.     });
  264. };
  266. /**
  267.  * @typedef {object} SheetMusic
  268.  * @property {object} data - Sheet music data
  269.  * @property {string} data.sheet_music - The AlphaTex of the sheet music
  270.  * @property {string[]} data.part_list - A list of the part (i.e. track) names
  271.  * @property {string[]} data.clefs - The clefs per staff
  272.  * @property {string} data.part - If not null, then the part of the current user in the sheet music
  273.  */
  275. /**
  276.  * Gets a specific piece of sheet music
  277.  * @function
  278.  * @param {object} data
  279.  * @param {string} data.sheetMusicId - The sheet music id to retrieve
  280.  * @returns {Promise<module:tmaApi~SheetMusic|module:tmaApi~ServerError>} - A promise containing sheet music information or an error
  281.  */
  282. export const getSpecificSheetMusic = (data) => {
  283.     return axios.request({
  284.         method: "GET",
  285.         url: "/sheet-music/specific",
  286.         params: data,
  287.     });
  288. };
  290. /**
  291.  * @typedef {object} SheetMusicPart
  292.  * @property {object} data - Part data
  293.  * @property {number[]} data.performance_expectation - A 1D array of even size with the ith index as the midi value and the i+1 index as the duration of that note for i%2==0
  294.  * @property {number[]} data.lower_upper - A 1D two valued array with the lower and upper midi values
  295.  * @property {number[]} data.measure_lengths - A collection of the lengths of each Measure. The ith index contains the length in seconds of the i+1 Measure
  296.  */
  298. /**
  299.  * Gets a specific part from a specific piece of sheet music
  300.  * @function
  301.  * @param {object} data - Music data
  302.  * @param {string} data.sheetMusicId - The sheet music id to retrieve
  303.  * @param {string} data.partName - The name of the part to be retrieved
  304.  * @returns {Promise<module:tmaApi~SheetMusicPart|module:tmaApi~ServerError>} - A promise containing part information or an error
  305.  */
  306. export const getPartSheetMusic = (data) => {
  307.     return axios.request({
  308.         method: "GET",
  309.         url: "/sheet-music/part",
  310.         params: data,
  311.     });
  312. };
  314. /**
  315.  * @typedef {object} MemberPostNewNoAnalysisPackage
  316.  * @property {string} performance_id The ID of the newly generated performance data
  317.  */
  319. /**
  320.  * Initalizes a performance for the current user for the provided sheet music
  321.  * @function
  322.  * @param {Object} data - Music data
  323.  * @param {string} data.performanceData - The performance data to be added
  324.  * @param {string} data.sheetMusicId - The sheet music id to add the performance to, also used to authenticate user so this is required
  325.  * @param {string} data.exerciseId - If not null then the performance will be attached to this exercise otherwise attached to sheet music
  326.  * @param {Boolean} data.isDurationExercise - If exercise, specify if it is a duration exercise
  327.  * @param {number} data.measureStart - Start of performance
  328.  * @param {number} data.measureEnd - End of performance
  329.  * @returns {Promise<module:tmaApi~MemberPostNewNoAnalysisPackage|module:tmaApi~ServerError>} - A promise containing the performance id or an error
  330.  */
  331. export const initializeRunningPerformance = (data) => {
  332.     return axios.post("/performance/new/no-analysis", data);
  333. };
  335. /**
  336.  * Adds a new performance for the current user for the provided sheet music and analyzes it immediately
  337.  * @function
  338.  * @param {Object} data
  339.  * @param {string} data.performanceData - The performance data to be added
  340.  * @param {string} data.sheetMusicId - The sheet music id to add the performance to, also used to authenticate user so this is required
  341.  * @param {string} data.exerciseId - If not null then the performance will be attached to this exercise otherwise attached to sheet music
  342.  * @param {Boolean} data.isDurationExercise - If exercise, specify if it is a duration exercise
  343.  * @param {number} data.measureStart - Start of performance
  344.  * @param {number} data.measureEnd - End of performance
  345.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  346.  */
  347. export const addPerformance = (data) => {
  348.     return axios.post("/performance/new/analysis", data);
  349. };
  351. /**
  352.  * Updates a stored performance with additional values
  353.  * @function
  354.  * @param {Object} data
  355.  * @param {string} data.performanceData - The performance data to be added
  356.  * @param {string} data.performanceId - The performance id to update
  357.  * @param {string} data.sheetMusicId - The sheet music id for the performance
  358.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  359.  */
  360. export const updateRunningPerformance = (data) => {
  361.     return axios.put("/performance/no-analysis", data);
  362. };
  364. /**
  365.  * Closes out a running performance with the most recent data and asks to analyze it
  366.  * @function
  367.  * @param {Object} data
  368.  * @param {string} data.performanceData - The performance data to be added
  369.  * @param {string} data.performanceId - The performance id to update
  370.  * @param {string} data.sheetMusicId - The sheet music id for the performance
  371.  * @param {string} data.exerciseId - If not null then the performance will be attached to this exercise otherwise attached to sheet music
  372.  * @param {Boolean} data.isDurationExercise - If exercise, specify if it is a duration exercise
  373.  * @param {number} data.measureStart - Start of performance
  374.  * @param {number} data.measureEnd - End of performance
  375.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  376.  */
  377. export const closeRunningPerformance = (data) => {
  378.     return axios.put("/performance/analysis", data);
  379. };
  381. /**
  382.  * Updates a choir member
  383.  * Must be an admin of the choir to update a member
  384.  * @function
  385.  * @param {object} data
  386.  * @param {string} data.memberId
  387.  * @param {string} data.memberType
  388.  * @param {string} data.memberRole
  389.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  390.  */
  391. export const constUpdateMember = (data) => {
  392.     return axios.put("/member/update", data);
  393. };
  395. /**
  396.  * Deletes a choir member
  397.  * Must be an admin of the choir to update a member
  398.  * @function
  399.  * @param {object} data
  400.  * @param {string} data.memberId
  401.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  402.  */
  403. export const deleteMember = (data) => {
  404.     return axios.delete("/member", data);
  405. };
  407. /**
  408.  * Gets all performances for the user for a given piece of sheet music
  409.  * @function
  410.  * @param {object} data
  411.  * @param {string} data.sheetMusicId
  412.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  413.  */
  414. export const getUsersPerformancesForSheetMusic = (data) => {
  415.     return axios.request({
  416.         method: "GET",
  417.         url: "/performance/all",
  418.         params: data,
  419.     });
  420. };
  422. /**
  423.  * @typedef {object} ExerciseGetPackage
  424.  * @property {string} sheet_music The Tex for the exercise
  425.  * @property {string[]} part_list A list of the part names of the AlphaTex
  426.  * @property {string[]} clefs A list of clefs per staff
  427.  * @property {number[]} performance_expectation A 1D array of even size with the ith index as the midi value and the i+1 index as the duration of that note for i%2==0
  428.  * @property {number[]} lower_upper A 1D two valued array with the lower and upper midi values
  429.  * @property {number[]} measure_lengths A collection of the lengths of each Measure. The ith index contains the length in seconds of the i+1 Measure
  430.  * @property {string} part The name of the main exercise to be rendered
  431.  */
  433. /**
  434.  * Gets the alphaTex for an exercise
  435.  * @function
  436.  * @param {Object} data
  437.  * @param {string} data.sheetMusicId - The sheet music id from which to generate the exercise
  438.  * @param {number} data.trackNumber - The track number to access (note: this is +1 more than the track index for any array)
  439.  * @param {number} data.staffNumber - The staff number to access (note: this is +1 more than the staff index for any array)
  440.  * @param {number} data.measureStart - The measure number to start with
  441.  * @param {number} data.measureEnd - The measure number to end with
  442.  * @param {Boolean} data.isDurationExercise - If true, generates a duration exercise otherwise just a normal exercise
  443.  * @returns {Promise<module:tmaApi~ExerciseGetPackage|module:tmaApi~ServerError>} - A promise containing information about the exercise or an error
  444.  */
  445. export const getExercise = (data) => {
  446.     return axios.request({
  447.         method: "GET",
  448.         url: `/exercise`,
  449.         params: data,
  450.     });
  451. };
  453. /**
  454.  * @typedef {object} SheetMusicPartGetPackage
  455.  * @property {string} sheet_music The created AlphaTex isolating the user's part
  456.  * @property {string[]} part_list A list of part (i.e. track) names in the generated AlphaTex
  457.  * @property {string[]} clefs Clefs per staff
  458.  * @property {number[]} performance_expectation A 1D array of even size with the ith index as the midi value and the i+1 index as the duration of that note for i%2==0
  459.  * @property {number[]} lower_upper A 1D two valued array with the lower and upper midi values
  460.  * @property {number[]} measure_lengths A collection of the lengths of each Measure. The ith index contains the length in seconds of the i+1 Measure
  461.  * @property {string} exerciseId The ID of the exercise created
  462.  */
  464. /**
  465.  * Gets the sheet music and performance data for the user's specific part
  466.  * @function
  467.  * @param {Object} data
  468.  * @param {string} data.sheetMusicId - The sheet music id to retrieve the part from
  469.  * @returns {Promise<module:tmaApi~SheetMusicPartGetPackage|module:tmaApi~ServerError>} - A promise containing information the sheet music or an error
  470.  */
  471. export const getSinglePartSheetMusic = (data) => {
  472.     return axios.request({
  473.         method: "GET",
  474.         url: `/sheet-music-part`,
  475.         params: data,
  476.     });
  477. };
  479. /**
  480.  * Adds selected part to sheet music for given member receiving nothing
  481.  * @function
  482.  * @param {Object} data
  483.  * @param {string} data.sheetMusicId - The sheet music id to which the part for the member is being added
  484.  * @param {string} data.part - The part from the sheet music that the member is selecting
  485.  * @param {string} data.memberId - The member who is selecting a part
  486.  * @returns {Promise<null|module:tmaApi~ServerError>} - A promise containing nothing on success or an error
  487.  */
  488. export const pickPartInSheetMusic = (data) => {
  489.     return axios.post("/sheet-music-part", data);
  490. };
  492. /**
  493.  * Gets performance progress of member for the given piece of sheet music
  494.  * @function
  495.  * @param {Object} data
  496.  * @param {string} data.sheetMusicId - The sheet music id to which the part for the member is being added
  497.  */
  498. export const getPerformanceProgress = (data) => {
  499.     return axios.request({
  500.         method: "GET",
  501.         url: `/performance-progress`,
  502.         params: data,
  503.     });
  504. };