diff --git a/sprints/sprint--confirm-unsubscribe.md b/sprints/sprint--confirm-unsubscribe.md new file mode 100644 index 0000000..99beaf5 --- /dev/null +++ b/sprints/sprint--confirm-unsubscribe.md @@ -0,0 +1,75 @@ +# Context +App users (landlord) can assign `tenantEmail` to a `BillingLocation`. + +This is a e-mail address will be used to notify the tenant when the rent is due and/or the utility bills are due. + +## E-mail verification +To prevent missuse and ensure that the e-mail is correct, before an e-mail address can be used by the automatic notification system, the tenant needs to verifies that he/she accepts to receive notifications. + +This verification is done via a link sent to the tenant in a verification-request e-mail, which is sent to the tenant automatically when the landloard (app user) assigns this e-mail address to a BillingLocation. + +Sending of this verification-request e-mail is handled by a system separate from NextJS app in `web-app` workspace. + +### Implementation details +Verification link points to the NextJS app in `web-app` workspace at path `/email/verify/[share-id]` (share-id is calculated using `generateShareId` from `/home/kneecola/projects/evidencija-rezija/web-app/app/lib/shareChecksum.ts`). + +The web page served at this path contains an text explanation and "Verify e-mail" button. + +The text includes the following information: +* what the web app is about - very short into +* why the e-mail was sent = because the landloard of the property X configured the rent (`BillingLocation.rentDueNotification`) and/or utility bills (`BillingLocation.billFwdStrategy`) to be delivered to that e-mail address +* what will hapen if he/she clicks on the "Verify e-mail" button = they will be receiving rent due (`BillingLocation.rentDueNotification`) or utility bills due (`BillingLocation.billFwdStrategy`) notification or both - 2x a month - depending on the config set by the landloard +* opt-out infomation (they can ignore this e-mail, but can also opt-out at any moment) + +If the user clicks the button "Verify e-mail" this triggers update of `BillingLocation.tenantEmailStatus`. + +Here's the expected stats flow: + +* landloard/app user assigns an an new address top `BillingLocation` -> `BillingLocation.tenantEmailStatus` is set to `EmailStatus.Unverified` +* a verification si sent to the entered e-mail address -> `BillingLocation.tenantEmailStatus` is set to `EmailStatus.VerificationPending` +* tenant click the link from the verification-requets e-mail -> `BillingLocation.tenantEmailStatus` is set to `EmailStatus.Verified` + +**Note:** status is updated for the `BillingLocation` inidcated by locationID (decoded from `[share-id]` param), and all subsequent matching `BillingLocation` records (matched by comparing `BillingLocation.name` and `BillingLocation.userId`). Similar pattern is already implemented in `updateOrAddLocation` fn in `locationAction.ts` (`updateScope === "subsequent"`). + +## E-mail unsubscribe +Tenant can out-out from receiving e-mail notifications at any time via an `unsubscribe` link included at the end of every mail sent to the tenant. + +### Implementation details +Verification link points to the NextJS app in `web-app` workspace at path `/email/unsubscribe/[share-id]` (share-id is calculated using `generateShareId` from `/home/kneecola/projects/evidencija-rezija/web-app/app/lib/shareChecksum.ts`). + +The web page served at this path contains an text explanation and "Confirm unsubscribe" button. + +The text includes the following information: +* what the web app is about - very short into +* why are they receiveing e-mails from this page = because their landlord for property X has configured the app to deliver rent due or utility bills due notification or both to that address +* what will hapen if they click on "Confirm unsubscribe" = they will no longer receive rent due / utility bull due reminders + +E-mail address's verification status is tracked via `BillingLocation.tenantEmailStatus`, which is set to `EmailStatus.Unsubscribed`. + +**Note:** status is updated for the `BillingLocation` inidcated by locationID (decoded from `[share-id]` param), and all subsequent matching `BillingLocation` records (matched by comparing `BillingLocation.name` and `BillingLocation.userId`). Similar pattern is already implemented in `updateOrAddLocation` fn in `locationAction.ts` (`updateScope === "subsequent"`). + +## E-mail status in `LocationCard.tsx` + +If the e-mail is not in `EmailStatus.Verifies` state for a given location, then this will be indicated in `LocationCard.tsx` as a sibling of `total-payed-label` block (`
`) + +## E-mail status in `LocationEditForm.tsx` + +Current e-mail status will be indicated as a sibling of `
`. +Use appropriate utf-8 icon for each status. + +# Logical Units of work + +Work will be split in logical units of work: + +* implement e-mail verification DB logic +* implement e-mail verification page + * create text both in croatian (hr.json) and english (en.json) + * implement share-id verification (see /home/kneecola/projects/evidencija-rezija/web-app/app/[locale]/share/proof-of-payment/per-bill/[id]/route.tsx) +* implement e-mail unsubscribe DB logic +* implement e-mail unsubscribe page + * create text both in croatian (hr.json) and english (en.json) + * implement share-id verification (see /home/kneecola/projects/evidencija-rezija/web-app/app/[locale]/share/proof-of-payment/per-bill/[id]/route.tsx) +* add email status to `LocationCard.tsx` +* add email status to `LocationEditForm.tsx` + +Each logical unit of work will be commited separatley. \ No newline at end of file