chore: Add experimental API annotation (#3227)

Author: mattcreaser

annotations/api/annotations.api

@@ -1,6 +1,9 @@
 public abstract interface annotation class com/amplifyframework/annotations/AmplifyFlutterApi : java/lang/annotation/Annotation {
 }
 
+public abstract interface annotation class com/amplifyframework/annotations/ExperimentalAmplifyApi : java/lang/annotation/Annotation {
+}
+
 public abstract interface annotation class com/amplifyframework/annotations/InternalAmplifyApi : java/lang/annotation/Annotation {
 }
 

annotations/src/main/java/com/amplifyframework/annotations/ExperimentalAmplifyApi.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package com.amplifyframework.annotations
+
+/**
+ * An API marked with this annotation is experimental. It may be changed or removed in a future release without
+ * following the standard deprecation cycle.
+ *
+ * Any usage of this API must be explicitly opted in with [OptIn] (e.g., `@OptIn(ExperimentalAmplifyApi::class)`) or
+ * by annotating the consuming declaration with [ExperimentalAmplifyApi].
+ */
+@MustBeDocumented
+@Retention(AnnotationRetention.BINARY)
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.TYPEALIAS,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY,
+    AnnotationTarget.FIELD,
+    AnnotationTarget.CONSTRUCTOR
+)
+@RequiresOptIn(
+    level = RequiresOptIn.Level.WARNING,
+    message = "This API is experimental. It may be changed or removed without notice."
+)
+annotation class ExperimentalAmplifyApi

build-logic/plugins/src/main/kotlin/KotlinConventionPlugin.kt

@@ -56,7 +56,7 @@ class KotlinConventionPlugin : Plugin<Project> {
 
             tasks.withType<KotlinCompile>().configureEach {
                 compilerOptions {
-                    freeCompilerArgs.addAll(amplifyInternalMarkers.map { "-opt-in=$it" })
+                    freeCompilerArgs.addAll(optInAnnotations.map { "-opt-in=$it" })
                     freeCompilerArgs.add("-Xconsistent-data-class-copy-visibility")
                 }
             }

build-logic/plugins/src/main/kotlin/KotlinMultiplatformConventionPlugin.kt

@@ -79,7 +79,7 @@ class KotlinMultiplatformConventionPlugin : Plugin<Project> {
             }
 
             compilerOptions {
-                freeCompilerArgs.addAll(amplifyInternalMarkers.map { "-opt-in=$it" })
+                freeCompilerArgs.addAll(optInAnnotations.map { "-opt-in=$it" })
                 freeCompilerArgs.add("-Xconsistent-data-class-copy-visibility")
             }
         }

build-logic/plugins/src/main/kotlin/Util.kt

@@ -18,11 +18,15 @@ import org.gradle.kotlin.dsl.getByType
  * permissions and limitations under the License.
  */
 
-val amplifyInternalMarkers = listOf(
+internal val amplifyInternalMarkers = listOf(
     "com.amplifyframework.annotations.InternalApiWarning",
     "com.amplifyframework.annotations.InternalAmplifyApi",
     "com.amplifyframework.annotations.AmplifyFlutterApi"
 )
 
+internal val optInAnnotations = amplifyInternalMarkers + listOf(
+    "com.amplifyframework.annotations.ExperimentalAmplifyApi"
+)
+
 internal val Project.libs
     get(): VersionCatalog = extensions.getByType<VersionCatalogsExtension>().named("libs")