Merge pull request #58 from appwrite/dev

feat: Kotlin SDK update for version 12.1.0

Author: abnegate

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+## 12.1.0
+
+* Deprecate `createVerification` method in `Account` service
+* Add `createEmailVerification` method in `Account` service
+
 ## 9.1.0
 
 * Add `incrementDocumentAttribute` and `decrementDocumentAttribute` support to `Databases` service

README.md

@@ -39,7 +39,7 @@ repositories {
 Next, add the dependency to your project's `build.gradle(.kts)` file:
 
 ```groovy
-implementation("io.appwrite:sdk-for-kotlin:12.0.0")
+implementation("io.appwrite:sdk-for-kotlin:12.1.0")
 ```
 
 ### Maven
@@ -50,7 +50,7 @@ Add this to your project's `pom.xml` file:
     <dependency>
         <groupId>io.appwrite</groupId>
         <artifactId>sdk-for-kotlin</artifactId>
-        <version>12.0.0</version>
+        <version>12.1.0</version>
     </dependency>
 </dependencies>
 ```

docs/examples/java/account/create-email-verification.md

@@ -0,0 +1,23 @@
+import io.appwrite.Client;
+import io.appwrite.coroutines.CoroutineCallback;
+import io.appwrite.services.Account;
+
+Client client = new Client()
+    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
+    .setProject("<YOUR_PROJECT_ID>") // Your project ID
+    .setSession(""); // The user session to authenticate with
+
+Account account = new Account(client);
+
+account.createEmailVerification(
+    "https://example.com", // url
+    new CoroutineCallback<>((result, error) -> {
+        if (error != null) {
+            error.printStackTrace();
+            return;
+        }
+
+        System.out.println(result);
+    })
+);
+

docs/examples/java/account/update-email-verification.md

@@ -0,0 +1,24 @@
+import io.appwrite.Client;
+import io.appwrite.coroutines.CoroutineCallback;
+import io.appwrite.services.Account;
+
+Client client = new Client()
+    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
+    .setProject("<YOUR_PROJECT_ID>") // Your project ID
+    .setSession(""); // The user session to authenticate with
+
+Account account = new Account(client);
+
+account.updateEmailVerification(
+    "<USER_ID>", // userId
+    "<SECRET>", // secret
+    new CoroutineCallback<>((result, error) -> {
+        if (error != null) {
+            error.printStackTrace();
+            return;
+        }
+
+        System.out.println(result);
+    })
+);
+

docs/examples/kotlin/account/create-email-verification.md

@@ -0,0 +1,14 @@
+import io.appwrite.Client
+import io.appwrite.coroutines.CoroutineCallback
+import io.appwrite.services.Account
+
+val client = Client()
+    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
+    .setProject("<YOUR_PROJECT_ID>") // Your project ID
+    .setSession("") // The user session to authenticate with
+
+val account = Account(client)
+
+val response = account.createEmailVerification(
+    url = "https://example.com"
+)

docs/examples/kotlin/account/update-email-verification.md

@@ -0,0 +1,15 @@
+import io.appwrite.Client
+import io.appwrite.coroutines.CoroutineCallback
+import io.appwrite.services.Account
+
+val client = Client()
+    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1") // Your API Endpoint
+    .setProject("<YOUR_PROJECT_ID>") // Your project ID
+    .setSession("") // The user session to authenticate with
+
+val account = Account(client)
+
+val response = account.updateEmailVerification(
+    userId = "<USER_ID>",
+    secret = "<SECRET>"
+)

src/main/kotlin/io/appwrite/Client.kt

@@ -58,11 +58,11 @@ class Client @JvmOverloads constructor(
     init {
         headers = mutableMapOf(
             "content-type" to "application/json",
-            "user-agent" to "AppwriteKotlinSDK/12.0.0 ${System.getProperty("http.agent")}",
+            "user-agent" to "AppwriteKotlinSDK/12.1.0 ${System.getProperty("http.agent")}",
             "x-sdk-name" to "Kotlin",
             "x-sdk-platform" to "server",
             "x-sdk-language" to "kotlin",
-            "x-sdk-version" to "12.0.0",
+            "x-sdk-version" to "12.1.0",
             "x-appwrite-response-format" to "1.8.0",
         )
 

src/main/kotlin/io/appwrite/services/Account.kt

@@ -1780,10 +1780,48 @@ class Account(client: Client) : Service(client) {
      * @return [io.appwrite.models.Token]
      */
     @Throws(AppwriteException::class)
+    suspend fun createEmailVerification(
+        url: String,
+    ): io.appwrite.models.Token {
+        val apiPath = "/account/verifications/email"
+
+        val apiParams = mutableMapOf<String, Any?>(
+            "url" to url,
+        )
+        val apiHeaders = mutableMapOf<String, String>(
+            "content-type" to "application/json",
+        )
+        val converter: (Any) -> io.appwrite.models.Token = {
+            io.appwrite.models.Token.from(map = it as Map<String, Any>)
+        }
+        return client.call(
+            "POST",
+            apiPath,
+            apiHeaders,
+            apiParams,
+            responseType = io.appwrite.models.Token::class.java,
+            converter,
+        )
+    }
+
+    /**
+     * Use this endpoint to send a verification message to your user email address to confirm they are the valid owners of that address. Both the **userId** and **secret** arguments will be passed as query parameters to the URL you have provided to be attached to the verification email. The provided URL should redirect the user back to your app and allow you to complete the verification process by verifying both the **userId** and **secret** parameters. Learn more about how to [complete the verification process](https://appwrite.io/docs/references/cloud/client-web/account#updateVerification). The verification link sent to the user's email address is valid for 7 days.
+     * 
+     * Please note that in order to avoid a [Redirect Attack](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.md), the only valid redirect URLs are the ones from domains you have set when adding your platforms in the console interface.
+     * 
+     *
+     * @param url URL to redirect the user back to your app from the verification email. Only URLs from hostnames in your project platform list are allowed. This requirement helps to prevent an [open redirect](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) attack against your project API.
+     * @return [io.appwrite.models.Token]
+     */
+    @Deprecated(
+        message = "This API has been deprecated since 1.8.0. Please use `Account.createEmailVerification` instead.",
+        replaceWith = ReplaceWith("io.appwrite.services.Account.createEmailVerification")
+    )
+    @Throws(AppwriteException::class)
     suspend fun createVerification(
         url: String,
     ): io.appwrite.models.Token {
-        val apiPath = "/account/verification"
+        val apiPath = "/account/verifications/email"
 
         val apiParams = mutableMapOf<String, Any?>(
             "url" to url,
@@ -1812,11 +1850,49 @@ class Account(client: Client) : Service(client) {
      * @return [io.appwrite.models.Token]
      */
     @Throws(AppwriteException::class)
+    suspend fun updateEmailVerification(
+        userId: String,
+        secret: String,
+    ): io.appwrite.models.Token {
+        val apiPath = "/account/verifications/email"
+
+        val apiParams = mutableMapOf<String, Any?>(
+            "userId" to userId,
+            "secret" to secret,
+        )
+        val apiHeaders = mutableMapOf<String, String>(
+            "content-type" to "application/json",
+        )
+        val converter: (Any) -> io.appwrite.models.Token = {
+            io.appwrite.models.Token.from(map = it as Map<String, Any>)
+        }
+        return client.call(
+            "PUT",
+            apiPath,
+            apiHeaders,
+            apiParams,
+            responseType = io.appwrite.models.Token::class.java,
+            converter,
+        )
+    }
+
+    /**
+     * Use this endpoint to complete the user email verification process. Use both the **userId** and **secret** parameters that were attached to your app URL to verify the user email ownership. If confirmed this route will return a 200 status code.
+     *
+     * @param userId User ID.
+     * @param secret Valid verification token.
+     * @return [io.appwrite.models.Token]
+     */
+    @Deprecated(
+        message = "This API has been deprecated since 1.8.0. Please use `Account.updateEmailVerification` instead.",
+        replaceWith = ReplaceWith("io.appwrite.services.Account.updateEmailVerification")
+    )
+    @Throws(AppwriteException::class)
     suspend fun updateVerification(
         userId: String,
         secret: String,
     ): io.appwrite.models.Token {
-        val apiPath = "/account/verification"
+        val apiPath = "/account/verifications/email"
 
         val apiParams = mutableMapOf<String, Any?>(
             "userId" to userId,
@@ -1846,7 +1922,7 @@ class Account(client: Client) : Service(client) {
     @Throws(AppwriteException::class)
     suspend fun createPhoneVerification(
     ): io.appwrite.models.Token {
-        val apiPath = "/account/verification/phone"
+        val apiPath = "/account/verifications/phone"
 
         val apiParams = mutableMapOf<String, Any?>(
         )
@@ -1878,7 +1954,7 @@ class Account(client: Client) : Service(client) {
         userId: String,
         secret: String,
     ): io.appwrite.models.Token {
-        val apiPath = "/account/verification/phone"
+        val apiPath = "/account/verifications/phone"
 
         val apiParams = mutableMapOf<String, Any?>(
             "userId" to userId,

src/main/kotlin/io/appwrite/services/Functions.kt

@@ -491,7 +491,7 @@ class Functions(client: Client) : Service(client) {
     /**
      * Create a deployment based on a template.
      * 
-     * Use this endpoint with combination of [listTemplates](https://appwrite.io/docs/server/functions#listTemplates) to find the template details.
+     * Use this endpoint with combination of [listTemplates](https://appwrite.io/docs/products/functions/templates) to find the template details.
      *
      * @param functionId Function ID.
      * @param repository Repository name of the template.

src/main/kotlin/io/appwrite/services/Sites.kt

@@ -486,7 +486,7 @@ class Sites(client: Client) : Service(client) {
     /**
      * Create a deployment based on a template.
      * 
-     * Use this endpoint with combination of [listTemplates](https://appwrite.io/docs/server/sites#listTemplates) to find the template details.
+     * Use this endpoint with combination of [listTemplates](https://appwrite.io/docs/products/sites/templates) to find the template details.
      *
      * @param siteId Site ID.
      * @param repository Repository name of the template.