First Commit

libraries/pushproviders/api/build.gradle.kts

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+plugins {
+    id("io.element.android-compose-library")
+}
+
+android {
+    namespace = "io.element.android.libraries.pushproviders.api"
+}
+
+dependencies {
+    implementation(projects.libraries.core)
+    implementation(projects.libraries.matrix.api)
+}

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/Config.kt

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2024, 2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.pushproviders.api
+
+data class Config(
+    val url: String,
+    val pushKey: String,
+)

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/Distributor.kt

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.pushproviders.api
+
+/**
+ * Firebase does not have the concept of distributor. So for Firebase, there will be one distributor:
+ * Distributor("Firebase", "Firebase").
+ *
+ * For UnifiedPush, for instance, the Distributor can be:
+ * Distributor("io.heckel.ntfy", "ntfy").
+ * But other values are possible.
+ */
+data class Distributor(
+    val value: String,
+    val name: String,
+) {
+    val fullName = "$name ($value)"
+}

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/PushData.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.pushproviders.api
+
+import io.element.android.libraries.matrix.api.core.EventId
+import io.element.android.libraries.matrix.api.core.RoomId
+
+/**
+ * Represent parsed data that the app has received from a Push content.
+ *
+ * @property eventId The Event Id.
+ * @property roomId The Room Id.
+ * @property unread Number of unread message.
+ * @property clientSecret data used when the pusher was configured, to be able to determine the session.
+ */
+data class PushData(
+    val eventId: EventId,
+    val roomId: RoomId,
+    val unread: Int?,
+    val clientSecret: String,
+)

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/PushHandler.kt

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.pushproviders.api
+
+interface PushHandler {
+    suspend fun handle(
+        pushData: PushData,
+        providerInfo: String,
+    )
+
+    suspend fun handleInvalid(
+        providerInfo: String,
+        data: String,
+    )
+}

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/PushProvider.kt

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.pushproviders.api
+
+import io.element.android.libraries.matrix.api.MatrixClient
+import io.element.android.libraries.matrix.api.core.SessionId
+
+/**
+ * This is the main API for this module.
+ */
+interface PushProvider {
+    /**
+     * Allow to sort providers, from lower index to higher index.
+     */
+    val index: Int
+
+    /**
+     * User friendly name.
+     */
+    val name: String
+
+    /**
+     * true if the Push provider supports multiple distributors.
+     */
+    val supportMultipleDistributors: Boolean
+
+    /**
+     * Return the list of available distributors.
+     */
+    fun getDistributors(): List<Distributor>
+
+    /**
+     * Register the pusher to the homeserver.
+     */
+    suspend fun registerWith(matrixClient: MatrixClient, distributor: Distributor): Result<Unit>
+
+    /**
+     * Return the current distributor, or null if none.
+     */
+    suspend fun getCurrentDistributorValue(sessionId: SessionId): String?
+
+    /**
+     * Return the current distributor, or null if none.
+     */
+    suspend fun getCurrentDistributor(sessionId: SessionId): Distributor?
+
+    /**
+     * Unregister the pusher.
+     */
+    suspend fun unregister(matrixClient: MatrixClient): Result<Unit>
+
+    /**
+     * To invoke when the session is deleted.
+     */
+    suspend fun onSessionDeleted(sessionId: SessionId)
+
+    suspend fun getPushConfig(sessionId: SessionId): Config?
+
+    fun canRotateToken(): Boolean
+
+    suspend fun rotateToken(): Result<Unit> {
+        error("rotateToken() not implemented, you need to override this method in your implementation")
+    }
+}

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/PusherSubscriber.kt

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.pushproviders.api
+
+import io.element.android.libraries.matrix.api.MatrixClient
+import io.element.android.libraries.matrix.api.exception.ClientException
+
+interface PusherSubscriber {
+    /**
+     * Register a pusher. Note that failure will be a [RegistrationFailure].
+     */
+    suspend fun registerPusher(matrixClient: MatrixClient, pushKey: String, gateway: String): Result<Unit>
+
+    /**
+     * Unregister a pusher.
+     */
+    suspend fun unregisterPusher(matrixClient: MatrixClient, pushKey: String, gateway: String): Result<Unit>
+}
+
+class RegistrationFailure(
+    val clientException: ClientException,
+    val isRegisteringAgain: Boolean
+) : Exception(clientException)