feat(data): Events API Contract shells

appsync/aws-appsync-core-amplify/build.gradle.kts → appsync/aws-appsync-amplify/build.gradle.kts

@@ -31,7 +31,7 @@ project.setProperty("VERSION_NAME", readVersion())
 group = properties["POM_GROUP"].toString()
 
 android {
-    namespace = "com.amplifyframework.aws.appsync.core"
+    namespace = "com.amplifyframework.aws.appsync.amplify"
     defaultConfig {
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }

appsync/aws-appsync-amplify/gradle.properties

@@ -0,0 +1,4 @@
+POM_ARTIFACT_ID=aws-appsync-amplify
+POM_NAME=Amplify Extensions for AWS AppSync
+POM_DESCRIPTION=Amplify Extensions for AWS AppSync
+POM_PACKAGING=aar

appsync/aws-appsync-events/src/main/java/com/amplifyframework/aws/appsync/events/Events.kt

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2025 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.aws.appsync.events
+
+import com.amplifyframework.aws.appsync.core.AppSyncAuthorizer
+import com.amplifyframework.aws.appsync.events.data.ChannelAuthorizers
+import com.amplifyframework.aws.appsync.events.data.EventsException
+import com.amplifyframework.aws.appsync.events.data.PublishResult
+import kotlinx.serialization.json.JsonElement
+
+/**
+ * Publish a single event to a channel.
+ *
+ * @property endpoint AWS AppSync Events endpoint.
+ * @param connectAuthorizer for AWS AppSync Websocket Pub/Sub connection.
+ * @param defaultChannelAuthorizers passed to created channels if not overridden.
+ */
+class Events(
+    val endpoint: String,
+    val connectAuthorizer: AppSyncAuthorizer,
+    val defaultChannelAuthorizers: ChannelAuthorizers
+) {
+
+    /**
+     * Publish a single event to a channel.
+     *
+     * @param channelName of the channel to publish to.
+     * @param event formatted in json.
+     * @param authorizer for the publish call. If not provided, the EventChannel publish authorizer will be used.
+     * @return result of publish.
+     */
+    @Throws(EventsException::class)
+    suspend fun publish(
+        channelName: String,
+        event: JsonElement,
+        authorizer: AppSyncAuthorizer = this.defaultChannelAuthorizers.publishAuthorizer
+    ): PublishResult {
+        TODO("Need to implement")
+    }
+
+    /**
+     * Publish a multiple events (up to 5) to a channel.
+     *
+     * @param channelName of the channel to publish to.
+     * @param events list of formatted json events.
+     * @param authorizer for the publish call. If not provided, the EventChannel publish authorizer will be used.
+     * @return result of publish.
+     */
+    @Throws(EventsException::class)
+    suspend fun publish(
+        channelName: String,
+        events: List<JsonElement>,
+        authorizer: AppSyncAuthorizer = this.defaultChannelAuthorizers.publishAuthorizer
+    ): PublishResult {
+        TODO("Need to implement")
+    }
+
+    /**
+     * Create a channel.
+     *
+     * @param channelName of the channel to use.
+     * @param authorizers for the channel to use for subscriptions and publishes.
+     * @return a channel to manage subscriptions and publishes.
+     */
+    @Throws(EventsException::class)
+    fun channel(
+        channelName: String,
+        authorizers: ChannelAuthorizers = this.defaultChannelAuthorizers,
+    ): EventsChannel {
+        TODO("Need to implement")
+    }
+
+    /**
+     * Method to disconnect from all channels.
+     *
+     * @param flushEvents set to true (default) to allow all pending publish calls to succeed before disconnecting.
+     * Setting to false will immediately disconnect, cancelling any in-progress or queued event publishes.
+     * @param authorizers for the channel to use for subscriptions and publishes.
+     * @return a channel to manage subscriptions and publishes.
+     */
+    @Throws(EventsException::class)
+    suspend fun disconnect(flushEvents: Boolean = true) {
+        TODO("Need to implement")
+    }
+}

appsync/aws-appsync-events/src/main/java/com/amplifyframework/aws/appsync/events/EventsChannel.kt

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2025 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.aws.appsync.events
+
+import com.amplifyframework.aws.appsync.core.AppSyncAuthorizer
+import com.amplifyframework.aws.appsync.events.data.ChannelAuthorizers
+import com.amplifyframework.aws.appsync.events.data.EventsException
+import com.amplifyframework.aws.appsync.events.data.EventsMessage
+import com.amplifyframework.aws.appsync.events.data.PublishResult
+import kotlinx.coroutines.flow.Flow
+import kotlinx.serialization.json.JsonElement
+
+/**
+ * A class to manage channel subscriptions and publishes
+ *
+ * @property name of the channel
+ * @property authorizers used for channel subscriptions and publishes
+ */
+class EventsChannel internal constructor(
+    val name: String,
+    val authorizers: ChannelAuthorizers
+) {
+
+    /**
+     * Subscribe to a channel.
+     *
+     * @param authorizer for the subscribe call. If not provided, the EventChannel subscribe authorizer will be used.
+     * @return flow of event messages. Collect flow to receive messages.
+     */
+    @Throws(EventsException::class)
+    fun subscribe(
+        authorizer: AppSyncAuthorizer = this.authorizers.subscribeAuthorizer
+    ): Flow<EventsMessage> {
+        TODO("Need to implement")
+    }
+
+    /**
+     * Publish a single event to a channel.
+     *
+     * @param event formatted in json.
+     * @param authorizer for the publish call. If not provided, the EventChannel publish authorizer will be used.
+     * @return result of publish.
+     */
+    @Throws(EventsException::class)
+    suspend fun publish(
+        event: JsonElement,
+        authorizer: AppSyncAuthorizer = this.authorizers.publishAuthorizer
+    ): PublishResult {
+        TODO("Need to implement")
+    }
+
+    /**
+     * Publish a multiple events (up to 5) to a channel.
+     *
+     * @param events list of formatted json events.
+     * @param authorizer for the publish call. If not provided, the EventChannel publish authorizer will be used.
+     * @return result of publish.
+     */
+    @Throws(EventsException::class)
+    suspend fun publish(
+        events: List<JsonElement>,
+        authorizer: AppSyncAuthorizer = this.authorizers.publishAuthorizer
+    ): PublishResult {
+        TODO("Need to implement")
+    }
+}

appsync/aws-appsync-events/src/main/java/com/amplifyframework/aws/appsync/events/data/ChannelAuthorizers.kt

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2025 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.aws.appsync.events.data
+
+import com.amplifyframework.aws.appsync.core.AppSyncAuthorizer
+
+/**
+ * Authorizers passed to a channel to manage subscriptions and publishes.
+ *
+ * @property subscribeAuthorizer used for subscription requests.
+ * @property publishAuthorizer used for publish requests.
+ * @constructor Pass subscribe and publisher authorizer types.
+ */
+data class ChannelAuthorizers(
+    val subscribeAuthorizer: AppSyncAuthorizer,
+    val publishAuthorizer: AppSyncAuthorizer
+)

appsync/aws-appsync-events/src/main/java/com/amplifyframework/aws/appsync/events/data/EventsException.kt

@@ -0,0 +1,94 @@
+/*
+ * Copyright 2025 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.aws.appsync.events.data
+
+/**
+ * Base class for exceptions thrown in Events library
+ *
+ * @param message of the exception.
+ * @param cause of the exception.
+ * @param recoverySuggestion recommendation to resolve exception.
+ */
+open class EventsException internal constructor(
+    message: String,
+    cause: Throwable? = null,
+    val recoverySuggestion: String? = null
+) : Exception(message, cause)
+
+/**
+ * Thrown when failing to connect to Events WebSocket.
+ */
+class ConnectException internal constructor(cause: Throwable?) : EventsException(
+    message = "Failed to connect to the Events Api",
+    cause = cause,
+    recoverySuggestion = "See the underlying exception for cause"
+)
+
+/**
+ * Thrown when call is unauthorized.
+ */
+class UnauthorizedException internal constructor() : EventsException(
+    message = "Unauthorized",
+    recoverySuggestion = "Check your authorizer and Event configuration values and try again"
+)
+
+/**
+ * Thrown when connection is unexpectedly closed.
+ */
+class ConnectionClosedException internal constructor(cause: Throwable? = null) : EventsException(
+    message = "The websocket connection was closed",
+    cause = cause,
+    recoverySuggestion = "Check your internet connection and try again"
+)
+
+/**
+ * Thrown when rate limit is exceeded.
+ */
+internal class RateLimitExceededException internal constructor() : EventsException(
+    message = "Rate limit exceeded",
+    recoverySuggestion = "Try again later"
+)
+
+/**
+ * Thrown when operation is unsupported.
+ */
+internal class UnsupportedOperationException internal constructor() : EventsException(
+    message = "WebSocket did not understand the operation",
+    recoverySuggestion = "This is not expected to occur. Contact AWS"
+)
+
+/**
+ * Thrown when resource is not found.
+ */
+internal class ResourceNotFoundException internal constructor() : EventsException(
+    message = "Resource not found",
+    recoverySuggestion = "Check Event configuration values and try again"
+)
+
+/**
+ * Thrown when hitting max subscription limit.
+ */
+class MaxSubscriptionsReachedException internal constructor(throwable: Throwable) : EventsException(
+    message = "Max number of subscriptions reached",
+    recoverySuggestion = "Unsubscribe from existing channels before attempting to subscribe."
+)
+
+/**
+ * Thrown when attempting to send too many events or invalid request.
+ */
+class BadRequestException internal constructor() : EventsException(
+    message = "Input exceeded 5 event limit",
+    recoverySuggestion = "Submit 5 events or less."
+)