docs: 📝 changelog (#260)

CHANGELOG.md

@@ -1,5 +1,52 @@
 # 3.2.0
 This release adds notifications to the orion infrastructure...
+## Schema changes
+- Introduced `NotificationEmailDelivery` entity to handle email notifications. It includes fields for tracking the notification, delivery attempts, and a discard flag.
+- Added `EmailDeliveryAttempt` entity to track each delivery attempt. It includes a status and timestamp.
+- Created `DeliveryStatus` union type that can be either `EmailSuccess` or `EmailFailure` (which includes an error status).
+- Introduced `Read` and `Unread` types to track if a notification has been read. Both are part of the `ReadOrUnread` union.
+- Started defining a `Notification` entity. It includes fields for the account, notification type, event, status, in-app visibility, creation timestamp, and recipient.
+- Defined RecipientType as a union of `MemberRecipient` and `ChannelRecipient`.
+- Introduced various notification types as part of the NotificationType union. Each type has specific fields relevant to the notification.
+- Added `ChannelSuspended, NftFeaturedOnMarketPlace, ChannelVerified, ChannelExcluded, VideoExcluded, NewChannelFollower, CommentPostedToVideo, VideoLiked, VideoDisliked, NftPurchased, CreatorReceivesAuctionBid, NftOffered, DirectChannelPaymentByMember, EnglishAuctionSettled, ChannelFundsWithdrawn, ChannelCreated, CommentReply, ReactionToComment, VideoPosted, NewAuction, NewNftOnSale, HigherBidPlaced, AuctionWon, AuctionLost, BidMadeCompletingAuction, NftRoyaltyPaid` types. Each type includes fields relevant to the specific notification.
+- Introduced `AccountNotificationPreferences` type to handle user notification preferences.
+- Added fields for each notification type, each of which is of `NotificationPreference` type.
+- Channel notifications include: `channelExcludedFromApp, videoExcludedFromApp, nftFeaturedOnMarketPlace, newChannelFollower, videoCommentCreated, videoLiked, videoDisliked, yppChannelVerified, yppSignupSuccessful, yppChannelSuspended, nftBought, creatorTimedAuctionExpired, bidMadeOnNft, royaltyReceived, channelPaymentReceived, channelReceivedFundsFromWg, newPayoutUpdatedByCouncil, channelFundsWithdrawn`.
+Member notifications include: `channelCreated, replyToComment, reactionToComment, videoPosted, newNftOnAuction, newNftOnSale, timedAuctionExpired, higherBidThanYoursMade, auctionWon, auctionLost, openAuctionBidCanBeWithdrawn, fundsFromCouncilReceived, fundsToExternalWalletSent, fundsFromWgReceived`.
+- Introduced `ChannelYppStatus` as a union type in the GraphQL schema. This type represents the YouTube Partner Program (YPP) status of a channel.
+The ChannelYppStatus can be one of three types: `YppUnverified, YppVerified, YppSuspended`.
+## Resolvers 
+- Ypp status mutation resolvers have been introduced, intended for the Ypp verification ops team:
+    - Added `verifyChannel` mutation is protected by the `OperatorOnly` middleware, meaning it can only be accessed by operators returning a list of `VerifyChannelResults` (each contaning the `id` of the new suspension, the `channelId` of the suspended channel, and the `createdAt` timestamp of when the suspension was created)
+    - Added `excludeChannel` mutation (protected by the `OperatorOnly` middleware) to the GraphQL schema. This mutation is used to exclude a channel. It takes channelId and rationale as arguments and returns an `ExcludeChannelResult` (contaning the `id` of the new suspension, the `channelId` of the suspended channel, and the `createdAt` timestamp of when the suspension was created)
+    - Added `suspendChannels` mutation (protected by the `OperatorOnly` middleware) to the GraphQL schema. This mutation is used to suspend. It takes `channelIds` as an argument and returns a list of `SuspendChannelResult` (each contaning the `id` of the new suspension, the `channelId` of the suspended channel, and the `createdAt` timestamp of when the suspension was created)
+- Notification-related resolvers (accessible only through the `AccountOnly` middleware) are intened for the use with the front end app:
+    - Added `markNotificationsAsRead` mutation. This mutation marks specified notifications as read. It takes an array of `notificationIds` and returns an object with an array of IDs of notifications that were successfully marked as read.
+    - Added `setAccountNotificationPreferences` mutation. This mutation updates the notification preferences for the current account. It takes an object of `newPreferences` and returns the updated notification preferences.
+    - Both mutations are protected by the `AccountOnly` middleware, meaning they can only be accessed by authenticated accounts.
+    - Added a helper function `maybeUpdateNotificationPreference` to update individual notification preferences if a new value is provided. This function is used in the `setAccountNotificationPreferences` mutation to update each preference.
+- Notification email attepmts and assets
+    - Added `setMaxAttemptsOnMailDelivery` mutation. This mutation sets the maximum number of attempts to deliver an email notification. It takes `newMaxAttempts` as an argument and returns the new maximum attempts. The mutation is protected by the `OperatorOnly` middleware.
+    - Introduced `setNewNotificationCenterPath` mutation. This mutation sets the new notification center path. It takes `newMaxAttempts` as an argument and returns the new maximum attempts. The mutation is protected by the `OperatorOnly` middleware.
+    - Added `setNewAppRootDomain` mutation. This mutation sets the new application root domain. It takes `newRootDomain` as an argument and returns an object indicating whether the new root domain was applied. The mutation is protected by the `OperatorOnly` middleware.
+## Mail Scheduler module
+- mail template generation using mjml (see `./src/auth-server/emails/templates/mjml/notification.html.mst.mjml`)
+- Introduced functions to handle email notifications.
+- Added `getMaxAttempts` function to fetch the maximum number of email delivery attempts from the configuration.
+- Added `mailsToDeliver` function to fetch all email notifications that have not been discarded.
+- Added `deliverEmails` function to process each email notification. It creates the email content, executes the delivery, and records the attempt. If the delivery is successful or the maximum number of attempts has been reached, the notification is discarded.
+- The `deliverEmails` function is called in the `main` function, which logs the result of the email delivery process.
+- The email delivery is meant (for the moment) to be scheduled via chron job (as explained on operator documentation)
+## Misc
+- several unit test have been introduced along with CI checks
+- Refactored migration logic in order to migrate global account counter, which will be used also to migrate Notifications counters in future releases
+## Environment
+- Added `EMAIL_NOTIFICATION_DELIVERY_MAX_ATTEMPTS` environment variable to configure the maximum number of attempts to deliver an email notification, before the scheduler stops attending them
+- Introduced `APP_ASSET_STORAGE` environment variable to specify the URL where the application's assets are stored.
+- Added `APP_NAME_ALT` environment variable to set an alternative name for the application.
+- Introduced `NOTIFICATION_ASSET_ROOT` environment variable to specify the URL where the notification icons are stored.
+## Documentation
+- added documentation for setting up the email scheduler having a [Sendgrid](https://sendgrid.com) account
 
 # 3.1.0
 

docs/operator-guide/index.md

@@ -17,6 +17,8 @@ To learn how to run your own instance of Atlas, please refer to the [Atlas opera
     - [Accessing user reports](./tutorials/reported-content.md)
     - [Excluding (censoring) content](./tutorials/excluding-content.md)
     - [Featuring content](./tutorials/featuring-content.md)
+    - [Backing up Orion database](./tutorials/backups.md)
+    - [Configuring email notifications](./tutorials/email-notifications.md)
 - Production deployment:
     - [Deploying Orion to production](./tutorials/deploying-orion.md)
     - [Upgrading Orion](./tutorials/upgrading-orion.md)

docs/operator-guide/tutorials/deploying-orion.md

@@ -13,6 +13,8 @@ If you're on a Linux server you can use the [convinience script](https://docs.do
 
 You will also need to own a domain where you'll be hosting your Orion instance. In this guide we'll be using `mygateway.com` as an example domain. To be able to use subdomains like `auth.mygateway.com` and `query.mygateway.com` you need to make sure that your domain is either configured with a [wildcard DNS record](https://developers.cloudflare.com/dns/manage-dns-records/reference/wildcard-dns-records/) or that you have added a separate DNS record for each of the subdomains.
 
+You will also need a sendgrid account with an api key in order to have email notifications being send.
+
 ## Step-by-step guide
 
 1. Copy the `.env`, `docker-compose.yml`, `postgres.conf` and `Caddyfile` from the [`examples`](../examples/) directory to your server.
@@ -21,6 +23,7 @@ You will also need to own a domain where you'll be hosting your Orion instance.
     1. Fill in all the secrets (`OPERATOR_SECRET`, `APP_PRIVATE_KEY`, `COOKIE_SECRET`) with proper, randomly generated values
     1. **Make sure that `ORION_ENV` is set to `production`!**
     1. Set `GATEWAY_ROOT_DOMAIN` to your Gateway's root domain, in our example case it'll be `mygateway.com`
+    1. Configure the email notification scheduler chron job in order to have notification delivery via email (see: [Email Notifications](./email-notifications.md))
 1. Prepare a production build of the Atlas app. Assuming you have already cloned the Atlas repository and configured the environment variables inside `packages/atlas/src/.env` as described in the [Atlas operator guide](https://github.com/Joystream/atlas/blob/master/docs/operator-guide.md), you'll also need to:
     1. Make sure the `VITE_ENV` value is set to `production`
     1. Set `VITE_PRODUCTION_ORION_AUTH_URL` to your Orion Auth API endpoint (`https://auth.mygateway.com/api/v1` in our example case)

docs/operator-guide/tutorials/email-notifications.md

@@ -5,6 +5,7 @@ This feature has been introduced in Orion starting from version 3.2.0
 The current implementation uses a chron job for executing the
 `src/lib/mail-scheduler/index.js` script at every specified interval.
 One execution of the above script file will make all the pending email notifications to be send. The plan in the future is to combine all the email for a particular account in a digest form.
+It's important to remark that currently we only support [Sendgrid](https://sendgrid.com) as transactional email service
 
 ## Sendgrid configuration
 Configure the `.env` variables with:

docs/operator-guide/tutorials/local-testing.md

@@ -127,6 +127,11 @@ Below you can find a list of all tutorials that explain how to perform various a
 - [Excluding (censoring) content](./tutorials/excluding-content.md)
 - [Featuring content](./tutorials/featuring-content.md)
 
+### Email notifications scheduler
+
+In order to allow notification delivery via email, follow the steps detailed in [Email Notifications](./email-notifications.md).
+
+
 ## Testing with Atlas
 
 You can test your local Orion instance with the local Atlas dev server, launched via `yarn atlas:dev`.