task: add documentation

Author: jwilkinson87

README.md

@@ -1,3 +1,66 @@
 # Ctrl Hub Kotlin SDK
 
-README to follow.
+*Please note: This SDK is a work in progress, and as such, this README could change at any time*
+
+## Overview
+
+The `sdk.kotlin` repository provides an SDK implemented in Kotlin for integrating with the Ctrl Hub APIs. The SDK interfaces with the Ctrl Hub APIs using the Ktor library.
+
+## Usage
+
+Include the SDK via Maven/Gradle. Package information is available [here](https://github.com/ctrl-hub/sdk.kotlin/packages/2363087).
+
+Example Gradle config:
+
+```declarative
+repositories {
+    google()
+    mavenCentral()
+    maven {
+        url = uri("https://maven.pkg.github.com/ctrl-hub/sdk.kotlin")
+        credentials {
+            username = "your-github-username"
+            password = "your-personal-access-token"
+        }
+    }
+}
+
+dependencies {
+    implementation "com.ctrlhub:your-sdk-version"
+}
+```
+Please note: although the SDK is available publicly through GitHub, GitHub's Maven repository requires a GitHub personal access token to make use of it.
+
+### Configuration
+
+Configuring the SDK to use either staging or production APIs is as simple as re-assigning the `environment` property:
+
+```kotlin
+Config.environment = Environment.STAGING    // For staging
+Config.environment = Environment.PRODUCTION // For production
+```
+
+### API object
+Interaction with the APIs is done via the `Api` class. This class exposes a number of factory methods for instantiating an `Api` object with either a default Ktor client, or a customised one.
+
+```Api.create()```
+
+### Routers
+Routers are used to encapsulate specific areas of the API. For example, the `VehiclesRouter` takes care of all Vehicle API interactions. Routers are attached to the `Api` object via extension properties. 
+
+#### Example usage of the `VehiclesRouter`:
+
+```kotlin
+val api = Api.create()
+val response: List<Vehicle> = api.vehicles.all("your-session-token", "organisation-id", VehicleIncludes.SpecificationModel)
+```
+
+## Example Usage
+
+```kotlin
+Config.environment = Environment.STAGING
+val api = Api.create()
+
+val response = api.vehicles.all("sess-123", "org-123", VehicleIncludes.SpecificationModel)
+println(response.size)
+```

src/main/kotlin/com/ctrlhub/core/Api.kt

@@ -10,13 +10,25 @@ import io.ktor.serialization.kotlinx.json.json
 import io.ktor.util.appendIfNameAbsent
 import kotlinx.serialization.json.Json
 
+/**
+ * The "facade" class through which interaction with the API occurs.
+ */
 class Api private constructor(httpClient: HttpClient) {
     companion object {
+        /**
+         * Creates a new Api instance with a default client
+         */
         fun create(): Api {
             val httpClient = KtorClientFactory.create()
             return Api(configureHttpClient(httpClient, Config.apiBaseUrl))
         }
 
+        /**
+         * Creates a new Api client, with a given HttpClient instance.
+         * Default config will be applied to this client
+         *
+         * @param httpClient HttpClient A ktor client instance
+         */
         fun create(httpClient: HttpClient): Api {
             return Api(httpClient)
         }

src/main/kotlin/com/ctrlhub/core/api/ApiException.kt

@@ -2,8 +2,15 @@ package com.ctrlhub.core.api
 
 import io.ktor.client.statement.*
 
+/**
+ * Represents an exception that occurred when interacting with the API
+ */
 open class ApiException(message: String, e: Throwable) : Exception(message, e)
 
+/**
+ * Represents a client based exception that occurred when interacting with the API.
+ * This is usually the result of a non-200 HTTP response code.
+ */
 class ApiClientException(message: String, val response: HttpResponse, e: Throwable) : ApiException(message, e) {
     fun statusCode(): Int {
         return response.status.value

src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehiclesRouter.kt

@@ -16,6 +16,9 @@ import io.ktor.client.request.get
 import io.ktor.client.request.header
 import io.ktor.http.headers
 
+/**
+ * Represents JSONAPI includes that are associated for vehicles
+ */
 enum class VehicleIncludes(val value: String) {
     Status("status"),
     Assignee("assignee"),
@@ -28,7 +31,20 @@ enum class VehicleIncludes(val value: String) {
     SpecificationModelManufacturer("specification.model.manufacturer")
 }
 
+/**
+ * A vehicles router that deals with the vehicles realm of the Ctrl Hub API
+ */
 class VehiclesRouter(httpClient: HttpClient) : Router(httpClient) {
+
+    /**
+     * Request all vehicles
+     *
+     * @param sessionToken String A valid session token gained after authentication
+     * @param organisationId String The organisation ID to retrieve all vehicles for
+     * @param includes A variable list of any includes, to return in the response. For example, VehicleIncludes.Specification will provide additional Specification attributes
+     *
+     * @return A list of all vehicles
+     */
     suspend fun all(sessionToken: String, organisationId: String, vararg includes: VehicleIncludes): List<Vehicle> {
         val includesQuery = if (includes.isNotEmpty()) {
             "?include=${includes.joinToString(",") { it.value }}"

src/main/kotlin/com/ctrlhub/core/auth/AuthRouter.kt

@@ -22,7 +22,19 @@ import io.ktor.http.*
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
 
+/**
+ * A router that deals with authenticating through the Ctrl Hub API
+ */
 class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
+
+    /**
+     * Initiates a flow for authentication. This needs to be called first, before completing
+     *
+     * @return A response containing a flow ID and other information associated with an auth flow
+     *
+     * @throws ApiClientException when a client based exception occurs, usually as a result of a non-200 HTTP response code
+     * @throws ApiException when another type of exception occurs
+     */
     suspend fun initiate(): AuthFlowResponse {
         return try {
             httpClient.get("${Config.authBaseUrl}/self-service/login/api").body()
@@ -33,6 +45,14 @@ class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
         }
     }
 
+    /**
+     * Provides a mechanism for refreshing a session
+     *
+     * @param sessionToken String A valid session token obtained via authentication
+     *
+     * @throws ApiClientException when a client based exception occurs, usually as a result of a non-200 HTTP response code
+     * @throws ApiException when another type of exception occurs
+     */
     suspend fun refresh(sessionToken: String): AuthFlowResponse {
         return try {
             httpClient.get("${Config.authBaseUrl}/self-service/login/api?refresh=true") {
@@ -47,6 +67,17 @@ class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
         }
     }
 
+    /**
+     * Completes an authentication flow. This is the second step of authentication, after calling initiate
+     *
+     * @param flowId String A flow ID obtainer via the initiate call
+     * @param payload LoginPayload A payload that is used to authenticate a user
+     *
+     * @return A response representing a completed authentication response. This will hold session information
+     *
+     * @throws ApiClientException when a client based exception occurs, usually as a result of a non-200 HTTP response code
+     * @throws ApiException when another type of exception occurs
+     */
     suspend fun complete(flowId: String, payload: LoginPayload): CompleteResponse {
         return try {
             httpClient.post("${Config.authBaseUrl}/self-service/login?flow=$flowId") {
@@ -66,6 +97,14 @@ class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
         }
     }
 
+    /**
+     * Invalidates a session
+     *
+     * @param sessionToken String A session token that will identify the session to be invalidated
+     *
+     * @return true if the session could be invalidated successfuly, false if not
+     * @throws ApiException If an exception occurred whilst attempting to invalidate a session
+     */
     suspend fun logout(sessionToken: String): Boolean {
         return try {
             val statusCode = httpClient.delete("${Config.authBaseUrl}/self-service/logout/api") {

src/main/kotlin/com/ctrlhub/core/auth/InvalidCredentialsException.kt

@@ -1,3 +1,6 @@
 package com.ctrlhub.core.auth
 
+/**
+ * Represents an exception that occurs when authentication failed due to invalid credentials
+ */
 class InvalidCredentialsException: Exception()

src/main/kotlin/com/ctrlhub/core/auth/payload/AuthPayloads.kt

@@ -7,7 +7,7 @@ import kotlinx.serialization.Serializable
 data class LoginPayload(
     val identifier: String,
     val password: String,
-    val method: String
+    val method: String = "password"
 )
 
 @Serializable

src/main/kotlin/com/ctrlhub/core/governance/OrganisationsRouter.kt

@@ -15,6 +15,9 @@ import io.ktor.client.request.get
 import io.ktor.client.request.header
 import io.ktor.http.headers
 
+/**
+ * An organisation router that deals with the organisations realm of the Ctrl Hub API
+ */
 class OrganisationsRouter(httpClient: HttpClient) : Router(httpClient) {
     suspend fun all(sessionToken: String): List<Organisation> {
         return try {

src/main/kotlin/com/ctrlhub/core/http/KtorClientFactory.kt

@@ -11,6 +11,11 @@ import io.ktor.serialization.kotlinx.json.json
 import io.ktor.util.appendIfNameAbsent
 import kotlinx.serialization.json.Json
 
+/**
+ * A wrapper around the Ktor client. This allows default configuration
+ * to be applied that is specific to the Ctrl Hub API, but is also flexible
+ * in that an existing Ktor client can be passed, and config is applied to that.
+ */
 object KtorClientFactory {
     private lateinit var httpClient: HttpClient
 

src/main/kotlin/com/ctrlhub/core/iam/IamRouter.kt

@@ -15,7 +15,18 @@ import io.ktor.client.request.get
 import io.ktor.client.request.header
 import io.ktor.http.headers
 
+/**
+ * A router that deals with the Iam realm of the Ctrl Hub API
+ */
 class IamRouter(httpClient: HttpClient) : Router(httpClient) {
+
+    /**
+     * Returns information about the currently authenticated user, based on a session token
+     *
+     * @param sessionToken String A valid session token obtained via authentication
+     *
+     * @return A user object providing information about a currently authenticated user
+     */
     suspend fun whoami(sessionToken: String): User {
         return try {
             val rawResponse = httpClient.get("${Config.apiBaseUrl}/v3/iam/whoami") {