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

Author: aallam

.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://raw.githubusercontent.com/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).