knee-cola/evidencija-rezija
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

(prompt) written prompt for implementing e-mail confirmation and unsubscribe

Browse Source
This commit is contained in:
Knee Cola
2025-12-29 17:37:25 +01:00
parent 7a0370da9b
commit 1cafe33386
1 changed files with 75 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
sprints/sprint--confirm-unsubscribe.md Normal file
View File

@@ -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 (`<div className="flex ml-1">`)
## E-mail status in `LocationEditForm.tsx`
Current e-mail status will be indicated as a sibling of `<div id="tenantEmail-error">`.
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.