updated documentation

Author: V-m1r

ContentAPI.md

@@ -12,7 +12,7 @@ The KinesteX Content API allows you to fetch workout plans, workouts, and exerci
 
 - **API Key**: You must have a valid API key provided by KinesteX.
 - **Company Name**: Your company's name as registered with KinesteX.
-- **Dependencies**: Ensure you have Kotlin Coroutines in your project and latest version of KinesteXSDK. Check latest version [here](https://jitpack.io/#KinesteX/KinesteX-SDK-Kotlin)
+- **Dependencies**: Ensure you have Kotlin Coroutines in your project and the latest version of KinesteXSDK. Check the latest version [here](https://jitpack.io/#KinesteX/KinesteX-SDK-Kotlin).
 
 ### Fetching Content
 
@@ -22,6 +22,8 @@ You can fetch different types of content by specifying the `ContentType`. The av
 - `ContentType.PLAN`
 - `ContentType.EXERCISE`
 
+Additionally, you can fetch lists of content by providing optional parameters such as `category`, `bodyParts`, `limit`, and `lastDocId` for pagination.
+
 Here's how you can fetch content:
 
 ```kotlin
@@ -33,18 +35,57 @@ btnApiRequest.setOnClickListener {
 
             // Switch to IO dispatcher for network request
             val result = withContext(Dispatchers.IO) {
+                // FOR FETCHING PLANS LIST
                 fetchContent(
                     apiKey = apiKey,
                     companyName = company,
                     contentType = ContentType.PLAN,
-                    title = "Circuit Training" // example plan
+                    category = "Cardio",
+                    limit = 5
                 )
 
-                // FOR FETCHING WORKOUT
-                // fetchContent(apiKey, company, ContentType.WORKOUT, title = "Fitness Lite")
-
-                // FOR FETCHING EXERCISE
-                // fetchContent(apiKey, company, ContentType.EXERCISE, title = "Squats")
+                // FOR FETCHING WORKOUTS LIST (with category and body parts)
+                // fetchContent(
+                //     apiKey = apiKey,
+                //     companyName = company,
+                //     contentType = ContentType.WORKOUT,
+                //     category = "Fitness",
+                //     bodyParts = listOf(BodyPart.ABS),
+                //     limit = 5
+                // )
+
+                // FOR FETCHING EXERCISES LIST (with body parts)
+                // fetchContent(
+                //     apiKey = apiKey,
+                //     companyName = company,
+                //     contentType = ContentType.EXERCISE,
+                //     bodyParts = listOf(BodyPart.ABS),
+                //     limit = 5
+                // )
+
+                // FOR FETCHING a Specific Plan
+                // fetchContent(
+                //     apiKey = apiKey,
+                //     companyName = company,
+                //     contentType = ContentType.PLAN,
+                //     title = "Circuit Training"
+                // )
+
+                // FOR FETCHING a Specific Workout
+                // fetchContent(
+                //     apiKey = apiKey,
+                //     companyName = company,
+                //     contentType = ContentType.WORKOUT,
+                //     title = "Fitness Lite"
+                // )
+
+                // FOR FETCHING a Specific Exercise
+                // fetchContent(
+                //     apiKey = apiKey,
+                //     companyName = company,
+                //     contentType = ContentType.EXERCISE,
+                //     title = "Squats"
+                // )
             }
 
             // Handle the result on the main thread
@@ -68,7 +109,7 @@ btnApiRequest.setOnClickListener {
 
 - **Button Click Listener**: When the button is clicked, a coroutine is launched in the lifecycle scope.
 - **Switch to IO Dispatcher**: The `withContext(Dispatchers.IO)` block ensures that the network request is performed on an IO thread, preventing UI blocking.
-- **Fetch Content**: The `fetchContent` function is called with the necessary parameters to fetch the desired content.
+- **Fetch Content**: The `fetchContent` function is called with the necessary parameters to fetch the desired content. You can uncomment the relevant lines to fetch lists or specific items based on your needs.
 - **Handle Result**: After fetching, the result is passed to `handleAPIResult` to process the response.
 
 ### Fetch Content Function
@@ -79,14 +120,24 @@ private suspend fun fetchContent(
     companyName: String,
     contentType: ContentType,
     id: String? = null,
-    title: String? = null
+    title: String? = null,
+    lang: String = "en",
+    category: String? = null,
+    lastDocId: String? = null,
+    limit: Int? = null,
+    bodyParts: List<BodyPart>? = null
 ): APIContentResult {
     return KinesteXAPI.fetchAPIContentData(
         apiKey = apiKey,
         companyName = companyName,
         contentType = contentType,
+        id = id,
         title = title,
-        id = id
+        lang = lang,
+        category = category,
+        lastDocId = lastDocId,
+        limit = limit,
+        bodyParts = bodyParts
     )
 }
 ```
@@ -99,6 +150,10 @@ private suspend fun fetchContent(
   - `contentType`: The type of content to fetch (`WORKOUT`, `PLAN`, `EXERCISE`).
   - `id` *(optional)*: Specific ID of the content.
   - `title` *(optional)*: Title of the content to search for.
+  - `category` *(optional)*: Filter content by category.
+  - `lastDocId` *(optional)*: Identifier for pagination to fetch the next set of results.
+  - `limit` *(optional)*: Limit the number of results returned.
+  - `bodyParts` *(optional)*: Filter workouts or exercises by targeted body parts using the `BodyPart` enum.
 - **Return Value**: An `APIContentResult` object containing the fetched data or an error message.
 
 ### Handling the API Result
@@ -124,6 +179,30 @@ private fun handleAPIResult(result: APIContentResult) {
             val prettyJson = gson.toJson(exercise)
             println("Exercise Data:\n$prettyJson")
         }
+        is APIContentResult.Workouts -> {
+            val workouts = result.workouts.workouts
+            workouts.forEach { workout ->
+                println("Workout Title: ${workout.title}")
+                println("Body Parts: ${workout.body_parts.joinToString { it.value }}")
+                println("LastDocId: ${result.workouts.lastDocId}")
+            }
+        }
+        is APIContentResult.Plans -> {
+            val plans = result.plans.plans
+            plans.forEach { plan ->
+                println("Plan Title: ${plan.title}")
+                println("Categories: ${plan.category.description}")
+                println("LastDocId: ${result.plans.lastDocId}")
+            }
+        }
+        is APIContentResult.Exercises -> {
+            val exercises = result.exercises.exercises
+            exercises.forEach { exercise ->
+                println("Exercise Title: ${exercise.title}")
+                println("Body Parts: ${exercise.body_parts.joinToString { it.value }}")
+                println("LastDocId: ${result.exercises.lastDocId}")
+            }
+        }
         is APIContentResult.Error -> {
             Toast.makeText(
                 this,
@@ -139,56 +218,80 @@ private fun handleAPIResult(result: APIContentResult) {
 
 - **APIContentResult**: A sealed class representing the result of the API request.
   - **Success Cases**:
-    - `Workout`: Contains a `WorkoutModel`.
-    - `Plan`: Contains a `PlanModel`.
-    - `Exercise`: Contains an `ExerciseModel`.
+    - `Workout`: Contains a single `WorkoutModel`.
+    - `Plan`: Contains a single `PlanModel`.
+    - `Exercise`: Contains a single `ExerciseModel`.
+    - `Workouts`: Contains a list of `WorkoutModel` along with `lastDocId` for pagination.
+    - `Plans`: Contains a list of `PlanModel` along with `lastDocId` for pagination.
+    - `Exercises`: Contains a list of `ExerciseModel` along with `lastDocId` for pagination.
   - **Error Case**:
     - `Error`: Contains an error message.
 - **Handling Data**:
-  - Use `Gson` with pretty printing to convert the result into a readable JSON format.
-  - Print the data to the console or handle it as needed in your application.
+  - Use `Gson` with pretty printing to convert single item results into a readable JSON format.
+  - Iterate through lists (`Workouts`, `Plans`, `Exercises`) and handle each item as needed.
+  - **Pagination**: After handling the current set of results, use the provided `lastDocId` to fetch the next set of data.
 - **Handling Errors**:
   - Display a toast message or handle the error appropriately.
 
----
-
-## Implementation Overview
-
-The core of the Content API lies in the `KinesteXAPI` class and related data models. Here's a brief overview:
+### Pagination with `lastDocId`
 
-### KinesteXAPI Class
+To implement pagination, utilize the `lastDocId` provided in the response of your initial request. This ID allows you to fetch the next set of results in subsequent API calls.
 
-Responsible for making network requests to the KinesteX server to fetch content data.
+#### Example: Fetching the Next Page of Workouts
 
 ```kotlin
-class KinesteXAPI {
-    companion object {
-        private const val BASE_API_URL = "https://admin.kinestex.com/api/v1/"
-
-        suspend fun fetchAPIContentData(
-            apiKey: String,
-            companyName: String,
-            contentType: ContentType,
-            id: String? = null, // id of the plan
-            title: String? = null,
-            lang: String = "en"
-        ): APIContentResult {
-            // Implementation details...
-        }
+// Initial Fetch
+val initialResult = fetchContent(
+    apiKey = apiKey,
+    companyName = company,
+    contentType = ContentType.WORKOUT,
+    category = "Fitness",
+    limit = 5
+)
+
+// Handle Initial Result
+handleAPIResult(initialResult)
+
+// Assume you have obtained lastDocId from the initialResult
+val lastDocId = when (initialResult) {
+    is APIContentResult.Workouts -> initialResult.workouts.lastDocId
+    else -> null
+}
 
-        private fun containsDisallowedCharacters(text: String): Boolean {
-            // Validation logic...
-        }
-    }
+// Fetch Next Page Using lastDocId
+if (lastDocId != null) {
+    val nextPageResult = fetchContent(
+        apiKey = apiKey,
+        companyName = company,
+        contentType = ContentType.WORKOUT,
+        category = "Fitness",
+        limit = 5,
+        lastDocId = lastDocId
+    )
+    
+    // Handle Next Page Result
+    handleAPIResult(nextPageResult)
 }
 ```
 
+#### Explanation
+
+1. **Initial Fetch**: Fetch the first set of workouts with a specified `limit`.
+2. **Handle Initial Result**: Process and display the fetched workouts.
+3. **Retrieve `lastDocId`**: Extract the `lastDocId` from the initial response to use for the next request.
+4. **Fetch Next Page**: Use the retrieved `lastDocId` to fetch the subsequent set of workouts.
+5. **Handle Next Page Result**: Process and display the next set of workouts.
+
+---
+
 #### Key Points
 
 - **Endpoints**: Constructs the appropriate endpoint based on `ContentType`.
 - **Headers**: Adds `x-api-key` and `x-company-name` to authenticate requests.
 - **Network Call**: Uses `OkHttpClient` to perform synchronous network calls.
 - **Error Handling**: Returns an `APIContentResult.Error` in case of failures.
+- **BodyPart Filtering**: Supports filtering by `BodyPart` enum to fetch targeted content lists.
+- **Pagination**: Utilizes `lastDocId` to implement pagination, allowing you to fetch subsequent pages of content.
 
 ### Data Models
 
@@ -198,7 +301,7 @@ Data classes representing the structure of the content:
 - **ExerciseModel**
 - **PlanModel**
 
-These models represent the data received from the API and are used throughout your application.
+These models represent the data received from the API and are used throughout your application. They now include `body_parts` as a list of `BodyPart` enums to ensure type safety and consistency.
 
 ---
 
@@ -228,13 +331,15 @@ val result = withContext(Dispatchers.IO) {
 - **Error Handling**: Always handle possible exceptions, especially when dealing with network requests.
 - **Thread Safety**: UI updates must occur on the main thread. Ensure that after fetching data on `Dispatchers.IO`, any UI operations are performed on the main thread.
 - **Asynchronous Programming**: Utilizing coroutines and proper dispatchers helps in writing asynchronous code that is easy to read and maintain.
+- **BodyPart Enum**: Utilize the `BodyPart` enum to specify targeted muscle groups when fetching workouts or exercises, ensuring consistency and type safety.
+- **Pagination**: Use the `lastDocId` from your API responses to fetch subsequent pages of content, enabling smooth and efficient data loading.
 
 ---
 
 ## Conclusion
 
-The KinesteX Content API provides a straightforward way to access workout content within your Android application. By following the usage examples and understanding the importance of coroutine dispatchers, you can efficiently integrate and handle content data.
+The KinesteX Content API provides a straightforward way to access workout content within your Android application. By following the usage examples and understanding the importance of coroutine dispatchers and pagination, you can efficiently integrate and handle content data.
 
-For any issues or further assistance, please contact KinesteX support at [support@kinestex.com](mailto:support@kinestex.com).
+With the added capability to fetch lists of workouts, plans, and exercises with filters like `category`, `bodyParts`, `limit`, and `lastDocId`, you have greater flexibility in customizing the content retrieval to suit your application's needs.
 
----
+For any issues or further assistance, please contact KinesteX support at [support@kinestex.com](mailto:support@kinestex.com).

app/build.gradle.kts

@@ -38,15 +38,15 @@ android {
 }
 
 dependencies {
-     implementation(project(":kinestexsdkkotlin"))
+    //implementation(project(":kinestexsdkkotlin"))
     implementation("androidx.core:core-ktx:1.9.0")
     implementation("com.google.code.gson:gson:2.8.8")
     implementation("androidx.appcompat:appcompat:1.6.1")
     implementation("com.google.android.material:material:1.11.0")
     implementation("androidx.constraintlayout:constraintlayout:2.1.4")
     testImplementation("junit:junit:4.13.2")
     androidTestImplementation("androidx.test.ext:junit:1.1.5")
-  // implementation("com.github.KinesteX:KinesteX-SDK-Kotlin:1.1.7")
+    implementation("com.github.KinesteX:KinesteX-SDK-Kotlin:1.1.8")
     androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
     implementation("androidx.activity:activity-ktx:1.9.0")
     implementation("androidx.lifecycle:lifecycle-livedata-ktx:2.8.1")

settings.gradle.kts

@@ -16,4 +16,4 @@ pluginManagement {
 
 rootProject.name = "KinesteXSDKKotlin"
 include(":app")
-include(":kinestexsdkkotlin")
+//include(":kinestexsdkkotlin")