From 49b71420690b1727d226519f7bbd3b4f6124759f Mon Sep 17 00:00:00 2001
From: Yusuf Musleh <yusuf@opencraft.com>
Date: Sun, 23 Jun 2024 17:10:51 +0300
Subject: [PATCH] chore: Add param/return types for v2 libs

---
 src/studio-home/data/api.js    |  6 ++++--
 src/studio-home/data/types.mjs | 31 +++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 2 deletions(-)
 create mode 100644 src/studio-home/data/types.mjs

diff --git a/src/studio-home/data/api.js b/src/studio-home/data/api.js
index 92d7dc93f9..f177657b92 100644
--- a/src/studio-home/data/api.js
+++ b/src/studio-home/data/api.js
@@ -1,3 +1,4 @@
+// @ts-check
 import { camelCaseObject, snakeCaseObject, getConfig } from '@edx/frontend-platform';
 import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth';
 
@@ -8,7 +9,6 @@ export const getCourseNotificationUrl = (url) => new URL(url, getApiBaseUrl()).h
 
 /**
  * Get's studio home data.
- * @param {string} search
  * @returns {Promise<Object>}
  */
 export async function getStudioHomeData() {
@@ -47,7 +47,9 @@ export async function getStudioHomeLibraries() {
  * @param {number} [customParams.page] - (optional) Page number of results
  * @param {number} [customParams.pageSize] - (optional) The number of results on each page, default `50`
  * @param {boolean} [customParams.pagination] - (optional) Whether pagination is supported, default `true`
- * @returns {Promise<Object>} - A Promise that resolves to the response data container the studio home v2 libraries.
+ * @param {string} [customParams.order] - (optional) Library field to order results by. Prefix with '-' for descending
+ * @param {string} [customParams.search] - (optional) Search query to filter v2 Libraries by
+ * @returns {Promise<import("./types.mjs").LibrariesV2Response>} - Promise that resolves to v2 libraries response data
  */
 export async function getStudioHomeLibrariesV2(customParams) {
   // Set default params if not passed in
diff --git a/src/studio-home/data/types.mjs b/src/studio-home/data/types.mjs
new file mode 100644
index 0000000000..fd07fa6683
--- /dev/null
+++ b/src/studio-home/data/types.mjs
@@ -0,0 +1,31 @@
+// @ts-check
+
+/**
+ * @typedef {Object} LibraryV2
+ * @property {string} id - The ID of the v2 library.
+ * @property {string} type - The type of the v2 library.
+ * @property {string} org - The organization associated with the v2 library.
+ * @property {string} slug - The slug for the v2 library.
+ * @property {string} title - The title of the v2 library.
+ * @property {string} description - The description of the v2 library.
+ * @property {number} numBlocks - The number of blocks in the v2 library.
+ * @property {number} version - The version of the v2 library.
+ * @property {string|null} lastPublished - The date when the v2 library was last published.
+ * @property {boolean} allowLti - Indicates if LTI is allowed.
+ * @property {boolean} allowPublicLearning - Indicates if public learning is allowed.
+ * @property {boolean} allowPublicRead - Indicates if public read is allowed.
+ * @property {boolean} hasUnpublishedChanges - Indicates if there are unpublished changes.
+ * @property {boolean} hasUnpublishedDeletes - Indicates if there are unpublished deletes.
+ * @property {string} license - The license of the v2 library.
+ */
+
+/**
+ * @typedef {Object} LibrariesV2Response
+ * @property {string|null} next - The URL for the next page of results, or null if there is no next page.
+ * @property {string|null} previous - The URL for the previous page of results, or null if there is no previous page.
+ * @property {number} count - The total number of v2 libraries.
+ * @property {number} numPages - The total number of pages.
+ * @property {number} currentPage - The current page number.
+ * @property {number} start - The starting index of the results.
+ * @property {LibraryV2[]} results - An array of library objects.
+ */