refactor: add type definitions for API responses

src/api/auth.js

@@ -53,6 +53,9 @@ const loginReq = {
         });
     },
 
+    /**
+     * @returns {Promise<{json: any}>}
+     */
     getConfig() {
         return request('config', {
             method: 'GET'

src/api/avatar.js

@@ -3,7 +3,7 @@ import { useUserStore } from '../stores';
 
 const avatarReq = {
     /**
-     * @type {import('../types/avatar').getAvatar}
+     * @type {import('../types/api/avatar').GetAvatar}
      */
     getAvatar(params) {
         return request(`avatars/${params.avatarId}`, {
@@ -18,22 +18,7 @@ const avatarReq = {
     },
 
     /**
-     * @typedef {{
-     *     n: number,
-     *     offset: number,
-     *     search: string,
-     *     userId: string,
-     *     user: 'me' | 'friends'
-     *     sort: 'created' | 'updated' | 'order' | '_created_at' | '_updated_at',
-     *     order: 'ascending' | 'descending',
-     *     releaseStatus: 'public' | 'private' | 'hidden' | 'all',
-     *     featured: boolean
-     * }} GetAvatarsParameter
-     */
-    /**
-     *
-     * @param {GetAvatarsParameter} params
-     * @returns {Promise<{json: any, params}>}
+     * @type {import('../types/api/avatar').GetAvatars}
      */
     getAvatars(params) {
         return request('avatars', {

src/api/friend.js

@@ -92,6 +92,11 @@ const friendReq = {
         });
     },
 
+    /**
+     * @param {any} params
+     * @param {string} userId
+     * @returns {Promise<{json: any, params: any, userId: string}>}
+     */
     deleteHiddenFriendRequest(params, userId) {
         return request(`user/${userId}/friendRequest`, {
             method: 'DELETE',

src/api/instance.js

@@ -5,7 +5,7 @@ import { useInstanceStore } from '../stores';
 
 const instanceReq = {
     /**
-     * @type {import('../types/instance').getInstance}
+     * @type {import('../types/api/instance').GetInstance}
      */
     getInstance(params) {
         const instanceStore = useInstanceStore();
@@ -22,19 +22,7 @@ const instanceReq = {
     },
 
     /**
-     * CreateInstanceParameter
-     * @typedef {Object} CreateInstanceParameter
-     * @property {string} worldId
-     * @property {string} type
-     * @property {string} region
-     * @property {string} ownerId
-     * @property {string[]} roleIds
-     * @property {string} groupAccessType
-     * @property {boolean} queueEnabled
-     */
-    /**
-     * @param {CreateInstanceParameter} params
-     * @returns {Promise<{json: any, params}>}
+     * @type {import('../types/api/instance').CreateInstance}
      */
     createInstance(params) {
         const instanceStore = useInstanceStore();
@@ -52,7 +40,7 @@ const instanceReq = {
     },
 
     /**
-     * @type {import('../types/instance').getInstanceShortName}
+     * @type {import('../types/api/instance').GetInstanceShortName}
      */
     getInstanceShortName(instance) {
         const params = {};

src/api/notification.js

@@ -1,6 +1,9 @@
 import { request } from '../service/request';
 import { useGroupStore, useNotificationStore } from '../stores';
 
+/**
+ * @returns {any}
+ */
 function getGalleryStore() {
     return useGroupStore();
 }
@@ -35,6 +38,10 @@ const notificationReq = {
         });
     },
 
+    /**
+     * @param {{n?: number, offset?: number}} params
+     * @returns {Promise<{json: any, params: any}>}
+     */
     getHiddenFriendRequests(params) {
         return request('auth/user/notifications', {
             method: 'GET',
@@ -52,6 +59,10 @@ const notificationReq = {
         });
     },
 
+    /**
+     * @param {{n?: number, offset?: number, type?: string}} params
+     * @returns {Promise<{json: any, params: any}>}
+     */
     getNotificationsV2(params) {
         return request('notifications', {
             method: 'GET',

src/api/user.js

@@ -1,6 +1,9 @@
 import { request } from '../service/request';
 import { useUserStore } from '../stores';
 
+/**
+ * @returns {string}
+ */
 function getCurrentUserId() {
     return useUserStore().currentUser.id;
 }
@@ -9,7 +12,7 @@ const userReq = {
     /**
      * Fetch user from API.
      * identifier of registered user
-     * @type {import('../types/user').getUser}
+     * @type {import('../types/api/user').GetUser}
      */
     getUser(params) {
         const userStore = useUserStore();
@@ -32,7 +35,7 @@ const userReq = {
 
     /**
      * Fetch user from cache if they're in it. Otherwise, calls API.
-     * @type {import('../types/user').getUser}
+     * @type {import('../types/api/user').GetCachedUser}
      */
     getCachedUser(params) {
         const userStore = useUserStore();
@@ -58,17 +61,7 @@ const userReq = {
     },
 
     /**
-     * @typedef {object} GetUsersParameters
-     * @property {number} n
-     * @property {number} offset
-     * @property {string} search
-     * @property {'nuisanceFactor' | 'created' | '_created_at' | 'last_login'} sort
-     * @property {'ascending' | 'descending'} order
-     */
-    /**
-     * Fetch multiple users from API.
-     * @param params {GetUsersParameters} filtering and sorting parameters
-     * @returns {Promise<{json: any, params}>}
+     * @type {import('../types/api/user').GetUsers}
      */
     getUsers(params) {
         return request('users', {
@@ -84,8 +77,8 @@ const userReq = {
     },
 
     /**
-     * @param params {string[]}
-     * @returns {Promise<{json: any, params}>}
+     * @param {string[]} params User tags to add
+     * @returns {Promise<{json: any, params: string[]}>}
      */
     addUserTags(params) {
         const userStore = useUserStore();
@@ -103,8 +96,8 @@ const userReq = {
     },
 
     /**
-     * @param params {string[]}
-     * @returns {Promise<{json: any, params}>}
+     * @param {string[]} params User tags to remove
+     * @returns {Promise<{json: any, params: string[]}>}
      */
     removeUserTags(params) {
         const userStore = useUserStore();
@@ -122,8 +115,8 @@ const userReq = {
     },
 
     /**
-     * @param params {{ userId: string }}
-     * @returns {Promise<{json: any, params}>}
+     * @param {{ userId: string }} params
+     * @returns {Promise<{json: any, params: { userId: string }}>}
      */
     getUserFeedback(params) {
         return request(`users/${params.userId}/feedback`, {
@@ -142,7 +135,7 @@ const userReq = {
 
     /**
      * Updates current user's status.
-     *  @type {import('../types/user').getCurrentUser}
+     * @type {import('../types/api/user').GetCurrentUser}
      */
     saveCurrentUser(params) {
         const userStore = useUserStore();
@@ -160,8 +153,8 @@ const userReq = {
     },
 
     /**
-     * @param params {{ offset: number, n: number }}
-     * @returns {Promise<{json: any, params}>}
+     * @param {{ offset: number, n: number }} params
+     * @returns {Promise<{json: any, params: { offset: number, n: number }}>}
      */
     getUserNotes(params) {
         return request(`userNotes`, {

src/api/world.js

@@ -3,7 +3,7 @@ import { useWorldStore } from '../stores';
 
 const worldReq = {
     /**
-     * @type {import('../types/world').getWorld}
+     * @type {import('../types/api/world').GetWorld}
      */
     getWorld(params) {
         const worldStore = useWorldStore();
@@ -47,22 +47,7 @@ const worldReq = {
     },
 
     /**
-     * @typedef {object} WorldSearchParameter
-     * @property {number} n
-     * @property {number} offset
-     * @property {string} search
-     * @property {string} userId
-     * @property {'me' | 'friend'} user
-     * @property {'popularity' | 'heat' | 'trust' | 'shuffle' | 'favorites' | 'reportScore' | 'reportCount' | 'publicationDate' | 'labsPublicationDate' | 'created' | '_created_at' | 'updated' | '_updated_at' | 'order'} sort
-     * @property {'ascending' | 'descending'} order
-     * @property {'public' | 'private' | 'hidden' | 'all'} releaseStatus
-     * @property {boolean} featured
-     */
-    /**
-     *
-     * @param {WorldSearchParameter} params
-     * @param {string?} option sub-path of calling endpoint
-     * @returns {Promise<{json: any, params, option}>}
+     * @type {import('../types/api/world').GetWorlds}
      */
     getWorlds(params, option) {
         const worldStore = useWorldStore();