Merge pull request #77 from mayorJAY/code-documentation

Write Code Documentations

src/main/kotlin/Novu.kt

@@ -22,6 +22,12 @@ import co.novu.api.WorkflowsApi
 import co.novu.helpers.RetrofitHelper
 import okhttp3.logging.HttpLoggingInterceptor
 
+/**
+ * A set of configurations used to construct Novu, these configurations ultimately control the way the SDK behaves.
+ *
+ * @author Shivam Shah <a href="https://github.com/nulllvoid">link</a>
+ * @author Joseph Olugbohunmi <a href="https://github.com/mayorJAY">link</a>
+ */
 data class NovuConfig(
     var apiKey: String = "",
     var backendUrl: String = "https://api.novu.co/v1/",
@@ -31,6 +37,27 @@ data class NovuConfig(
     var apiLogLevel: HttpLoggingInterceptor.Level = HttpLoggingInterceptor.Level.BASIC,
 )
 
+/**
+ * Main entry point for initialising and accessing the functionalities provided in the SDK.
+ * This class provides two constructors. It can be constructed either by providing an API key
+ * (gotten from [the web portal](https://web.novu.co/settings)) or by providing
+ * an instance of [NovuConfig].
+ *
+ * For example:
+ *
+ * ```
+ * // Using an API key only
+ * val novu = Novu("apiKey")
+ *
+ *
+ * // Using NovuConfig
+ * val novuConfig = NovuConfig("apiKey")
+ * val novu = Novu(novuConfig)
+ * ```
+ *
+ * @author Shivam Shah <a href="https://github.com/nulllvoid">link</a>
+ * @author Joseph Olugbohunmi <a href="https://github.com/mayorJAY">link</a>
+ */
 class Novu(
     val config: NovuConfig,
 ) {

src/main/kotlin/dto/response/TriggerResponse.kt

@@ -4,5 +4,5 @@ data class TriggerResponse(
     var acknowledged: Boolean? = null,
     var status: String? = null,
     var transactionId: String? = null,
-    var error: List<Any>? = null,
+    var error: List<String>? = null,
 )

src/main/kotlin/extensions/BlueprintsExtensions.kt

@@ -9,11 +9,22 @@ import mu.KotlinLogging
 
 private val logger = KotlinLogging.logger {}
 
+/**
+ * Retrieve a list of Blueprints grouped by Category.
+ * @return [ResponseWrapper] with [BlueprintsResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.getBlueprintsByCategory(): ResponseWrapper<BlueprintsResponse>? {
     val response = blueprintsApi.getBlueprintsByCategory()
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Retrieve a Blueprint.
+ * @param templateId the ID of a Template
+ * @return [Blueprint]
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.getBlueprint(templateId: String): Blueprint? {
     val response = blueprintsApi.getBlueprint(templateId)
     return response.extractResponse(logger, config.enableLogging)

src/main/kotlin/extensions/ChangesExtentions.kt

@@ -11,6 +11,14 @@ import java.math.BigInteger
 
 private val logger = KotlinLogging.logger {}
 
+/**
+ * Retrieve a list of Changes. This function supports pagination.
+ * @param page the page number to be retrieved
+ * @param limit the size of the page to be retrieved
+ * @param promoted the state of the Changes to be retrieved
+ * @return [PaginatedResponseWrapper] with a list of [ChangesResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.changes(
     page: BigInteger? = null,
     limit: BigInteger? = null,
@@ -20,16 +28,33 @@ suspend fun Novu.changes(
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Retrieve the count of all available Changes.
+ * @return [ResponseWrapper] with [BigInteger] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.changesCount(): ResponseWrapper<BigInteger>? {
     val response = changesApi.getChangesCount()
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Apply a list of Changes.
+ * @param request an instance of [ChangesRequest]
+ * @return [ResponseWrapper] with a list of [ChangesResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.applyBulkChanges(request: ChangesRequest): ResponseWrapper<List<ChangesResponse>>? {
     val response = changesApi.applyBulkChanges(request)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Apply a particular Change.
+ * @param changeId the ID of the Change to be applied
+ * @return [ResponseWrapper] with a list of [ChangesResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.applyChange(changeId: String): ResponseWrapper<List<ChangesResponse>>? {
     val response = changesApi.applyChange(changedId = changeId)
     return response.extractResponse(logger, config.enableLogging)

src/main/kotlin/extensions/EnvironmentsExtentions.kt

@@ -12,21 +12,44 @@ import mu.KotlinLogging
 
 private val logger = KotlinLogging.logger {}
 
+/**
+ * Retrieve the data of the current Environment.
+ * @return [ResponseWrapper] with [GetEnvironmentResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.currentEnvironment(): ResponseWrapper<GetEnvironmentResponse>? {
     val response = environmentsApi.getCurrentEnvironment()
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Create an Environment.
+ * @param request an instance of [CreateEnvironmentRequest]
+ * @return [ResponseWrapper] with [GetEnvironmentResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.createEnvironment(request: CreateEnvironmentRequest): ResponseWrapper<GetEnvironmentResponse>? {
     val response = environmentsApi.createEnvironment(request)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Retrieve a list of Environments.
+ * @return [ResponseWrapper] with a list of [GetEnvironmentResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.environments(): ResponseWrapper<List<GetEnvironmentResponse>>? {
     val response = environmentsApi.getEnvironments()
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Update an Environment.
+ * @param environmentId the ID of the Environment to be updated
+ * @param request an instance of [UpdateEnvironmentRequest]
+ * @return [ResponseWrapper] with [GetEnvironmentResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.updateEnvironment(
     environmentId: String,
     request: UpdateEnvironmentRequest,
@@ -35,11 +58,21 @@ suspend fun Novu.updateEnvironment(
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Retrieve a list of API Keys.
+ * @return [ResponseWrapper] with a list of [ApiKeys] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.apiKeys(): ResponseWrapper<List<ApiKeys>>? {
     val response = environmentsApi.getApiKeys()
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Regenerate API Keys.
+ * @return [ResponseWrapper] with a list of [ApiKeys] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.regenrateApiKey(): ResponseWrapper<List<ApiKeys>>? {
     val response = environmentsApi.regenerateApiKey()
     return response.extractResponse(logger, config.enableLogging)

src/main/kotlin/extensions/EventsExtensions.kt

@@ -11,21 +11,45 @@ import mu.KotlinLogging
 
 private val logger = KotlinLogging.logger {}
 
+/**
+ * Trigger an event such as sending notification to subscribers.
+ * @param body an instance of [TriggerEventRequest]
+ * @return [ResponseWrapper] with [TriggerResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.trigger(body: TriggerEventRequest): ResponseWrapper<TriggerResponse>? {
     val response = eventsApi.triggerEvent(body)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Trigger multiple events in a single transaction.
+ * @param body an instance of [BulkTriggerEventRequest]
+ * @return [ResponseWrapper] with a list of [TriggerResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.bulkTrigger(body: BulkTriggerEventRequest): ResponseWrapper<List<TriggerResponse>>? {
     val response = eventsApi.bulkTriggerEvent(body)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Broadcast an event to all existing subscribers.
+ * @param body an instance of [BroadcastEventRequest]
+ * @return [ResponseWrapper] with [TriggerResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.broadcast(body: BroadcastEventRequest): ResponseWrapper<TriggerResponse>? {
     val response = eventsApi.broadcastEvent(body)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Cancel a running event.
+ * @param transactionId the transaction ID of the running event
+ * @return [ResponseWrapper] with [Boolean] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.cancelTriggerEvent(transactionId: String): ResponseWrapper<Boolean>? {
     val response = eventsApi.cancelTriggerEvent(transactionId)
     return response.extractResponse(logger, config.enableLogging)

src/main/kotlin/extensions/ExecutionDetailsExtentions.kt

@@ -8,6 +8,13 @@ import mu.KotlinLogging
 
 private val logger = KotlinLogging.logger {}
 
+/**
+ * Retrieve a list of Execution Details.
+ * @param notificationId the ID of a Notification
+ * @param subscriberId the ID of a Subscriber
+ * @return [ResponseWrapper] with a list of [ExecutionDetails] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.executionDetails(
     notificationId: String,
     subscriberId: String,

src/main/kotlin/extensions/FeedsExtentions.kt

@@ -9,16 +9,33 @@ import mu.KotlinLogging
 
 private val logger = KotlinLogging.logger {}
 
+/**
+ * Create a Feed.
+ * @param body an instance of [CreateByNameRequest]
+ * @return [ResponseWrapper] with [FeedResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.createFeed(body: CreateByNameRequest): ResponseWrapper<FeedResponse>? {
     val response = feedsApi.createFeed(body)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Retrieve a list of Feeds.
+ * @return [ResponseWrapper] with a list of [FeedResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.feeds(): ResponseWrapper<List<FeedResponse>>? {
     val response = feedsApi.getFeeds()
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Delete a Feed.
+ * @param feedId the ID of the Feed to be deleted
+ * @return [ResponseWrapper] with [FeedResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.deleteFeed(feedId: String): ResponseWrapper<FeedResponse>? {
     val response = feedsApi.deleteFeed(feedId)
     return response.extractResponse(logger, config.enableLogging)

src/main/kotlin/extensions/InboundParseExtentions.kt

@@ -7,6 +7,11 @@ import mu.KotlinLogging
 
 private val logger = KotlinLogging.logger {}
 
+/**
+ * Validate the mx record setup for the inbound parse functionality.
+ * @return [ValidateMxRecordSetupForInboundParseResponse]
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.validateMxRecordSetupForInboundParse(): ValidateMxRecordSetupForInboundParseResponse? {
     val response = inboundParseApi.validateMxRecordSetupForInboundParse()
     return response.extractResponse(logger, config.enableLogging)

src/main/kotlin/extensions/IntegrationsExtentions.kt

@@ -9,26 +9,55 @@ import mu.KotlinLogging
 
 private val logger = KotlinLogging.logger {}
 
+/**
+ * Retrieve a list of Integrations associated with the API key provided.
+ * @return [ResponseWrapper] with a list of [IntegrationResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.integrations(): ResponseWrapper<List<IntegrationResponse>>? {
     val response = integrationsApi.getIntegrations()
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Create an Integration.
+ * @param request an instance of [IntegrationRequest]
+ * @return [ResponseWrapper] with [IntegrationResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.createIntegration(request: IntegrationRequest): ResponseWrapper<IntegrationResponse>? {
     val response = integrationsApi.createIntegration(request)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Retrieve a list of active Integrations associated with the API key provided.
+ * @return [ResponseWrapper] with a list of [IntegrationResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.activeIntegrations(): ResponseWrapper<List<IntegrationResponse>>? {
     val response = integrationsApi.getActiveIntegrations()
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Retrieve the status of a Provider's Webhook.
+ * @param providerId the ID of the Provider whose status is to be retrieved
+ * @return [ResponseWrapper] with a list of [IntegrationResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.providerWebhook(providerId: String): ResponseWrapper<Boolean>? {
     val response = integrationsApi.getProviderWebhook(providerId)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Update an Integration.
+ * @param integrationId the ID of the Integration to be updated
+ * @param request an instance of [IntegrationRequest]
+ * @return [ResponseWrapper] with [IntegrationResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.updateIntegration(
     integrationId: String,
     request: IntegrationRequest,
@@ -37,11 +66,23 @@ suspend fun Novu.updateIntegration(
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Delete an Integration.
+ * @param integrationId the ID of the Integration to be deleted
+ * @return [ResponseWrapper] with a list of [IntegrationResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.deleteIntegration(integrationId: String): ResponseWrapper<List<IntegrationResponse>>? {
     val response = integrationsApi.deleteIntegration(integrationId)
     return response.extractResponse(logger, config.enableLogging)
 }
 
+/**
+ * Set a particular Integration as the primary Integration.
+ * @param integrationId the ID of the Integration to be set as primary
+ * @return [ResponseWrapper] with a list of [IntegrationResponse] as the response data
+ * @throws [Exception] if a problem occurred talking to the server or if there is a connection error
+ */
 suspend fun Novu.setIntegrationAsPrimary(integrationId: String): ResponseWrapper<IntegrationResponse>? {
     val response = integrationsApi.setPrimaryIntegration(integrationId)
     return response.extractResponse(logger, config.enableLogging)