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

Merge branch 'feature/email-confirm-unsubscribe' into develop

Browse Source
This commit is contained in:
Knee Cola
2025-12-29 23:31:25 +01:00
parent 96abb5fffe f42366c00b
commit 7a526c5a85
19 changed files with 953 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.claude/settings.local.json
View File

@@ -23,7 +23,8 @@
"Bash(curl:*)",
"Bash(git mv:*)",
"Bash(rmdir:*)",
"Bash(mkdir:*)"
"Bash(mkdir:*)",
"Bash(git diff:*)"
]
},
"enableAllProjectMcpServers": true,

27
email-server-worker/README.md Normal file
View File

@@ -0,0 +1,27 @@
# Email Server Worker
This workspace contains the email server worker service for the Evidencija Režija tenant notification system.
## Purpose
This service manages email operations by:
- Polling MongoDB for email status changes
- Detecting unverified tenant emails (EmailStatus.Unverified)
- Sending verification emails to tenants
- Updating email status to VerificationPending
- Sending scheduled notifications (rent due, utility bills)
## Architecture
This is a standalone background worker service that:
- Runs independently from the Next.js web-app
- Communicates via the shared MongoDB database
- Integrates with email service provider (e.g., Mailgun, SendGrid)
## Setup
TBD
## Environment Variables
TBD

27
email-server-worker/sent-mail-tester.mjs Normal file
View File

@@ -0,0 +1,27 @@
import FormData from "form-data"; // form-data v4.0.1
import Mailgun from "mailgun.js"; // mailgun.js v11.1.0
async function sendSimpleMessage() {
const mailgun = new Mailgun(FormData);
const mg = mailgun.client({
username: "api",
key: process.env.API_KEY || "f581edcac21ec14d086ef25e36f04432-e61ae8dd-e207f22b",
// When you have an EU-domain, you must specify the endpoint:
url: "https://api.eu.mailgun.net"
});
try {
console.log("Sending email...");
const data = await mg.messages.create("rezije.app", {
from: "Mailgun Sandbox <support@rezije.app>",
to: ["Nikola Derezic <nikola.derezic@gmail.com>"],
subject: "Hello Nikola Derezic",
text: "Congratulations Nikola Derezic, you just sent an email with Mailgun! You are truly awesome!",
});
console.log(data); // logs response data
} catch (error) {
console.log(error); //logs any error
}
}
sendSimpleMessage();

8
evidencija-rezija.code-workspace
View File

@@ -12,6 +12,14 @@
"name": "🔧 housekeeping",
"path": "housekeeping"
},
{
"name": "📧 mailgun-webhook",
"path": "mailgun-webhook"
},
{
"name": "⚙️ email-server-worker",
"path": "email-server-worker"
},
{
"name": "📦 root",
"path": "."

23
mailgun-webhook/README.md Normal file
View File

@@ -0,0 +1,23 @@
# Mailgun Webhook Handler
This workspace contains the Mailgun webhook handler service for processing email events related to the Evidencija Režija tenant notification system.
## Purpose
This service handles email verification and status updates by:
- Detecting new tenant email addresses (EmailStatus.Unverified)
- Sending verification emails via Mailgun
- Updating email status to VerificationPending
- Processing webhook events from Mailgun (bounces, complaints, etc.)
## Architecture
This is a separate system from the Next.js web-app that communicates via the shared MongoDB database.
## Setup
TBD
## Environment Variables
TBD

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

@@ -0,0 +1,83 @@
# 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. It detects newly assigned addresses from their status bein equal `EmailStatus.Unverified`. The two systems don't talk to each other at all - what's holding them together is the DB.
### 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 cerifies if the [share-id] is correct and if not it shows 404 page.
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 `BillingLocation.name` 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 to `BillingLocation` -> `BillingLocation.tenantEmailStatus` is set to `EmailStatus.Unverified`
* an automated system detects that a new address was set (as indicated by `EmailStatus.Unverified` status), it then sets verification-email -> `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 (later in time) matching `BillingLocation` records (matched by comparing `BillingLocation.name`, `BillingLocation.userId` and `BillingLocation.tenantEmail`). 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` ... search of examples of how this function is used).
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 `BillingLocation.name` 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 (later in time) matching `BillingLocation` records (matched by comparing `BillingLocation.name`, `BillingLocation.userId` and `BillingLocation.tenantEmail`). 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.Verified` 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:
```
{/* Email status indicator should go here */}
<div id="tenantEmail-error" aria-live="polite" aria-atomic="true">
...
```
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.

117
web-app/app/[locale]/email/unsubscribe/[id]/EmailUnsubscribePage.tsx Normal file
View File

@@ -0,0 +1,117 @@
'use client';
import { useTranslations } from 'next-intl';
import { useState } from 'react';
import { unsubscribeTenantEmail } from '@/app/lib/actions/emailActions';
import { CheckCircleIcon } from '@heroicons/react/24/outline';
interface EmailUnsubscribePageProps {
shareId: string;
isVerified: boolean;
}
export default function EmailUnsubscribePage({ shareId, isVerified }: EmailUnsubscribePageProps) {
const t = useTranslations('email-unsubscribe-page');
const [isUnsubscribing, setIsUnsubscribing] = useState(false);
const [isUnsubscribed, setIsUnsubscribed] = useState(false);
const [error, setError] = useState<string | null>(null);
const handleUnsubscribe = async () => {
setIsUnsubscribing(true);
setError(null);
try {
const result = await unsubscribeTenantEmail(shareId);
if (result.success) {
setIsUnsubscribed(true);
} else {
setError(result.message || t('error.unknown'));
}
} catch (err) {
setError(t('error.unknown'));
} finally {
setIsUnsubscribing(false);
}
};
if (isUnsubscribed) {
return (
<div className="card bg-base-100 shadow-xl max-w-2xl mx-auto mt-8">
<div className="card-body">
<div className="flex justify-center mb-4">
<CheckCircleIcon className="h-16 w-16 text-success" />
</div>
<h2 className="card-title text-center justify-center text-success">
{t('success.title')}
</h2>
<p className="text-center">{t('success.message')}</p>
</div>
</div>
);
}
if (error) {
return (
<div className="card bg-base-100 shadow-xl max-w-2xl mx-auto mt-8">
<div className="card-body">
<h2 className="card-title text-error">{t('error.title')}</h2>
<p>{error}</p>
</div>
</div>
);
}
if (!isVerified) {
return (
<div className="card bg-base-100 shadow-xl max-w-2xl mx-auto mt-8">
<div className="card-body">
<h2 className="card-title text-warning">{t('not-allowed.title')}</h2>
<p>{t('not-allowed.message')}</p>
</div>
</div>
);
}
return (
<div className="card bg-base-100 shadow-xl max-w-2xl mx-auto mt-8">
<div className="card-body">
<h2 className="card-title mb-3">{t('title')}</h2>
<div className="space-y-4">
<div>
<h3 className="font-semibold text-lg">{t('about.title')}</h3>
<p>{t('about.description')}</p>
</div>
<div>
<h3 className="font-semibold text-lg">{t('why.title')}</h3>
<p>{t('why.description')}</p>
</div>
<div>
<h3 className="font-semibold text-lg">{t('what-happens.title')}</h3>
<p>{t('what-happens.description')}</p>
</div>
</div>
<div className="card-actions justify-center mt-6">
<button
className="btn btn-error"
onClick={handleUnsubscribe}
disabled={isUnsubscribing}
>
{isUnsubscribing ? (
<>
<span className="loading loading-spinner"></span>
{t('button.unsubscribing')}
</>
) : (
t('button.unsubscribe')
)}
</button>
</div>
</div>
</div>
);
}

45
web-app/app/[locale]/email/unsubscribe/[id]/page.tsx Normal file
View File

@@ -0,0 +1,45 @@
import { Suspense } from 'react';
import EmailUnsubscribePage from './EmailUnsubscribePage';
import { Main } from '@/app/ui/Main';
import { getDbClient } from '@/app/lib/dbClient';
import { BillingLocation, EmailStatus } from '@/app/lib/db-types';
import { extractShareId, validateShareChecksum } from '@/app/lib/shareChecksum';
import { notFound } from 'next/navigation';
export default async function Page({ params: { id } }: { params: { id: string } }) {
// Extract and validate share ID
const extracted = extractShareId(id);
if (!extracted) {
notFound();
}
const { locationId, checksum } = extracted;
// Validate checksum
if (!validateShareChecksum(locationId, checksum)) {
notFound();
}
// Fetch location to check email status
const dbClient = await getDbClient();
const location = await dbClient.collection<BillingLocation>("lokacije")
.findOne(
{ _id: locationId },
{ projection: { tenantEmail: 1, tenantEmailStatus: 1 } }
);
if (!location || !location.tenantEmail) {
notFound();
}
// Check if email is verified
const isVerified = location.tenantEmailStatus === EmailStatus.Verified;
return (
<Main>
<Suspense fallback={<div className="text-center p-8">Loading...</div>}>
<EmailUnsubscribePage shareId={id} isVerified={isVerified} />
</Suspense>
</Main>
);
}

122
web-app/app/[locale]/email/verify/[id]/EmailVerifyPage.tsx Normal file
View File

@@ -0,0 +1,122 @@
'use client';
import { useTranslations } from 'next-intl';
import { useState } from 'react';
import { verifyTenantEmail } from '@/app/lib/actions/emailActions';
import { CheckCircleIcon } from '@heroicons/react/24/outline';
interface EmailVerifyPageProps {
shareId: string;
isPending: boolean;
}
export default function EmailVerifyPage({ shareId, isPending }: EmailVerifyPageProps) {
const t = useTranslations('email-verify-page');
const [isVerifying, setIsVerifying] = useState(false);
const [isVerified, setIsVerified] = useState(false);
const [error, setError] = useState<string | null>(null);
const handleVerify = async () => {
setIsVerifying(true);
setError(null);
try {
const result = await verifyTenantEmail(shareId);
if (result.success) {
setIsVerified(true);
} else {
setError(result.message || t('error.unknown'));
}
} catch (err) {
setError(t('error.unknown'));
} finally {
setIsVerifying(false);
}
};
if (isVerified) {
return (
<div className="card bg-base-100 shadow-xl max-w-2xl mx-auto mt-8">
<div className="card-body">
<div className="flex justify-center mb-4">
<CheckCircleIcon className="h-16 w-16 text-success" />
</div>
<h2 className="card-title text-center justify-center text-success">
{t('success.title')}
</h2>
<p className="text-center">{t('success.message')}</p>
</div>
</div>
);
}
if (error) {
return (
<div className="card bg-base-100 shadow-xl max-w-2xl mx-auto mt-8">
<div className="card-body">
<h2 className="card-title text-error">{t('error.title')}</h2>
<p>{error}</p>
</div>
</div>
);
}
if (!isPending) {
return (
<div className="card bg-base-100 shadow-xl max-w-2xl mx-auto mt-8">
<div className="card-body">
<h2 className="card-title text-warning">{t('not-allowed.title')}</h2>
<p>{t('not-allowed.message')}</p>
</div>
</div>
);
}
return (
<div className="card bg-base-100 shadow-xl max-w-2xl mx-auto mt-8">
<div className="card-body">
<h2 className="card-title mb-3">{t('title')}</h2>
<div className="space-y-4">
<div>
<h3 className="font-semibold text-lg">{t('about.title')}</h3>
<p>{t('about.description')}</p>
</div>
<div>
<h3 className="font-semibold text-lg">{t('why.title')}</h3>
<p>{t('why.description')}</p>
</div>
<div>
<h3 className="font-semibold text-lg">{t('what-happens.title')}</h3>
<p>{t('what-happens.description')}</p>
</div>
<div>
<h3 className="font-semibold text-lg">{t('opt-out.title')}</h3>
<p>{t('opt-out.description')}</p>
</div>
</div>
<div className="card-actions justify-center mt-6">
<button
className="btn btn-primary"
onClick={handleVerify}
disabled={isVerifying}
>
{isVerifying ? (
<>
<span className="loading loading-spinner"></span>
{t('button.verifying')}
</>
) : (
t('button.verify')
)}
</button>
</div>
</div>
</div>
);
}

45
web-app/app/[locale]/email/verify/[id]/page.tsx Normal file
View File

@@ -0,0 +1,45 @@
import { Suspense } from 'react';
import EmailVerifyPage from './EmailVerifyPage';
import { Main } from '@/app/ui/Main';
import { getDbClient } from '@/app/lib/dbClient';
import { BillingLocation, EmailStatus } from '@/app/lib/db-types';
import { extractShareId, validateShareChecksum } from '@/app/lib/shareChecksum';
import { notFound } from 'next/navigation';
export default async function Page({ params: { id } }: { params: { id: string } }) {
// Extract and validate share ID
const extracted = extractShareId(id);
if (!extracted) {
notFound();
}
const { locationId, checksum } = extracted;
// Validate checksum
if (!validateShareChecksum(locationId, checksum)) {
notFound();
}
// Fetch location to check email status
const dbClient = await getDbClient();
const location = await dbClient.collection<BillingLocation>("lokacije")
.findOne(
{ _id: locationId },
{ projection: { tenantEmail: 1, tenantEmailStatus: 1 } }
);
if (!location || !location.tenantEmail) {
notFound();
}
// Check if email is pending verification
const isPending = location.tenantEmailStatus === EmailStatus.VerificationPending;
return (
<Main>
<Suspense fallback={<div className="text-center p-8">Loading...</div>}>
<EmailVerifyPage shareId={id} isPending={isPending} />
</Suspense>
</Main>
);
}

175
web-app/app/lib/actions/emailActions.ts Normal file
View File

@@ -0,0 +1,175 @@
'use server';
import { getDbClient } from '../dbClient';
import { BillingLocation, EmailStatus } from '../db-types';
import { extractShareId, validateShareChecksum } from '../shareChecksum';
import { revalidatePath } from 'next/cache';
export type EmailActionResult = {
success: boolean;
message?: string;
};
/**
* Verify tenant email address
* Updates the email status to Verified for the location and all subsequent matching locations
*
* @param shareId - The share ID from the verification link (locationId + checksum)
* @returns Result indicating success or failure
*/
export async function verifyTenantEmail(shareId: string): Promise<EmailActionResult> {
// Extract and validate share ID
const extracted = extractShareId(shareId);
if (!extracted) {
return {
success: false,
message: 'Invalid verification link'
};
}
const { locationId, checksum } = extracted;
// Validate checksum
if (!validateShareChecksum(locationId, checksum)) {
return {
success: false,
message: 'Invalid verification link'
};
}
// Get database client
const dbClient = await getDbClient();
// Fetch the location to get userId, name, tenantEmail, and yearMonth
const location = await dbClient.collection<BillingLocation>("lokacije")
.findOne(
{ _id: locationId },
{ projection: { userId: 1, name: 1, tenantEmail: 1, yearMonth: 1 } }
);
if (!location) {
return {
success: false,
message: 'Location not found'
};
}
if (!location.tenantEmail) {
return {
success: false,
message: 'No tenant email configured for this location'
};
}
// Update current and all subsequent matching locations
// Match by: userId, name, tenantEmail, and yearMonth >= current
const result = await dbClient.collection<BillingLocation>("lokacije").updateMany(
{
userId: location.userId,
name: location.name,
tenantEmail: location.tenantEmail,
$or: [
{ "yearMonth.year": { $gt: location.yearMonth.year } },
{
"yearMonth.year": location.yearMonth.year,
"yearMonth.month": { $gte: location.yearMonth.month }
}
]
},
{
$set: {
tenantEmailStatus: EmailStatus.Verified
}
}
);
// Revalidate paths to refresh UI
revalidatePath('/[locale]', 'layout');
return {
success: true,
message: `Email verified successfully (${result.modifiedCount} location(s) updated)`
};
}
/**
* Unsubscribe tenant from email notifications
* Updates the email status to Unsubscribed for the location and all subsequent matching locations
*
* @param shareId - The share ID from the unsubscribe link (locationId + checksum)
* @returns Result indicating success or failure
*/
export async function unsubscribeTenantEmail(shareId: string): Promise<EmailActionResult> {
// Extract and validate share ID
const extracted = extractShareId(shareId);
if (!extracted) {
return {
success: false,
message: 'Invalid unsubscribe link'
};
}
const { locationId, checksum } = extracted;
// Validate checksum
if (!validateShareChecksum(locationId, checksum)) {
return {
success: false,
message: 'Invalid unsubscribe link'
};
}
// Get database client
const dbClient = await getDbClient();
// Fetch the location to get userId, name, tenantEmail, and yearMonth
const location = await dbClient.collection<BillingLocation>("lokacije")
.findOne(
{ _id: locationId },
{ projection: { userId: 1, name: 1, tenantEmail: 1, yearMonth: 1 } }
);
if (!location) {
return {
success: false,
message: 'Location not found'
};
}
if (!location.tenantEmail) {
return {
success: false,
message: 'No tenant email configured for this location'
};
}
// Update current and all subsequent matching locations
// Match by: userId, name, tenantEmail, and yearMonth >= current
const result = await dbClient.collection<BillingLocation>("lokacije").updateMany(
{
userId: location.userId,
name: location.name,
tenantEmail: location.tenantEmail,
$or: [
{ "yearMonth.year": { $gt: location.yearMonth.year } },
{
"yearMonth.year": location.yearMonth.year,
"yearMonth.month": { $gte: location.yearMonth.month }
}
]
},
{
$set: {
tenantEmailStatus: EmailStatus.Unsubscribed
}
}
);
// Revalidate paths to refresh UI
revalidatePath('/[locale]', 'layout');
return {
success: true,
message: `Unsubscribed successfully (${result.modifiedCount} location(s) updated)`
};
}

27
web-app/app/lib/actions/locationActions.ts
View File

@@ -2,7 +2,7 @@
import { z } from 'zod';
import { getDbClient } from '../dbClient';
import { BillingLocation, FileAttachment, YearMonth } from '../db-types';
import { BillingLocation, FileAttachment, YearMonth, EmailStatus } from '../db-types';
import { ObjectId } from 'mongodb';
import { withUser } from '@/app/lib/auth';
import { AuthenticatedUser } from '../types/next-auth';
@@ -22,6 +22,7 @@ export type State = {
tenantTown?: string[];
autoBillFwd?: string[];
tenantEmail?: string[];
tenantEmailStatus?: string[];
billFwdStrategy?: string[];
rentDueNotification?: string[];
rentDueDay?: string[];
@@ -44,6 +45,7 @@ const FormSchema = (t:IntlTemplateFn) => z.object({
tenantTown: z.string().max(27).optional().nullable(),
autoBillFwd: z.boolean().optional().nullable(),
tenantEmail: z.string().email(t("tenant-email-invalid")).optional().or(z.literal("")).nullable(),
tenantEmailStatus: z.enum([EmailStatus.Unverified, EmailStatus.VerificationPending, EmailStatus.Verified, EmailStatus.Unsubscribed]).optional().nullable(),
billFwdStrategy: z.enum(["when-payed", "when-attached"]).optional().nullable(),
rentDueNotification: z.boolean().optional().nullable(),
rentDueDay: z.coerce.number().min(1).max(31).optional().nullable(),
@@ -122,6 +124,7 @@ export const updateOrAddLocation = withUser(async (user:AuthenticatedUser, locat
tenantTown: formData.get('tenantTown') || null,
autoBillFwd: formData.get('autoBillFwd') === 'on',
tenantEmail: formData.get('tenantEmail') || null,
tenantEmailStatus: formData.get('tenantEmailStatus') as "unverified" | "verification-pending" | "verified" | "unsubscribed" | undefined,
billFwdStrategy: formData.get('billFwdStrategy') as "when-payed" | "when-attached" | undefined,
rentDueNotification: formData.get('rentDueNotification') === 'on',
rentDueDay: formData.get('rentDueDay') || null,
@@ -147,6 +150,7 @@ export const updateOrAddLocation = withUser(async (user:AuthenticatedUser, locat
tenantTown,
autoBillFwd,
tenantEmail,
tenantEmailStatus,
billFwdStrategy,
rentDueNotification,
rentDueDay,
@@ -172,6 +176,20 @@ export const updateOrAddLocation = withUser(async (user:AuthenticatedUser, locat
};
}
// SECURITY: Validate email status transitions
// - If email changed: force to Unverified (prevents spoofing verified status)
// - If email unchanged: only allow client to reset to Unverified (via reset button)
// All other status transitions (Unverified→VerificationPending, VerificationPending→Verified)
// must happen server-side through other mechanisms (email verification links, etc.)
const emailHasChanged = currentLocation.tenantEmail !== (tenantEmail || null);
const clientWantsToReset = tenantEmailStatus === EmailStatus.Unverified;
const finalEmailStatus = emailHasChanged
? EmailStatus.Unverified // Email changed: force reset
: clientWantsToReset
? EmailStatus.Unverified // Client initiated reset: allow it
: (currentLocation.tenantEmailStatus || EmailStatus.Unverified); // Otherwise: keep current status
// Handle different update scopes
if (updateScope === "current" || !updateScope) {
// Update only the current location (default behavior)
@@ -190,6 +208,7 @@ export const updateOrAddLocation = withUser(async (user:AuthenticatedUser, locat
tenantTown: tenantTown || null,
autoBillFwd: autoBillFwd || false,
tenantEmail: tenantEmail || null,
tenantEmailStatus: finalEmailStatus,
billFwdStrategy: billFwdStrategy || "when-payed",
rentDueNotification: rentDueNotification || false,
rentDueDay: rentDueDay || null,
@@ -221,6 +240,7 @@ export const updateOrAddLocation = withUser(async (user:AuthenticatedUser, locat
tenantTown: tenantTown || null,
autoBillFwd: autoBillFwd || false,
tenantEmail: tenantEmail || null,
tenantEmailStatus: finalEmailStatus,
billFwdStrategy: billFwdStrategy || "when-payed",
rentDueNotification: rentDueNotification || false,
rentDueDay: rentDueDay || null,
@@ -245,6 +265,7 @@ export const updateOrAddLocation = withUser(async (user:AuthenticatedUser, locat
tenantTown: tenantTown || null,
autoBillFwd: autoBillFwd || false,
tenantEmail: tenantEmail || null,
tenantEmailStatus: finalEmailStatus,
billFwdStrategy: billFwdStrategy || "when-payed",
rentDueNotification: rentDueNotification || false,
rentDueDay: rentDueDay || null,
@@ -268,6 +289,7 @@ export const updateOrAddLocation = withUser(async (user:AuthenticatedUser, locat
tenantTown: tenantTown || null,
autoBillFwd: autoBillFwd || false,
tenantEmail: tenantEmail || null,
tenantEmailStatus: tenantEmailStatus as EmailStatus || EmailStatus.Unverified,
billFwdStrategy: billFwdStrategy || "when-payed",
rentDueNotification: rentDueNotification || false,
rentDueDay: rentDueDay || null,
@@ -343,6 +365,7 @@ export const updateOrAddLocation = withUser(async (user:AuthenticatedUser, locat
tenantTown: tenantTown || null,
autoBillFwd: autoBillFwd || false,
tenantEmail: tenantEmail || null,
tenantEmailStatus: tenantEmailStatus as EmailStatus || EmailStatus.Unverified,
billFwdStrategy: billFwdStrategy || "when-payed",
rentDueNotification: rentDueNotification || false,
rentDueDay: rentDueDay || null,
@@ -446,6 +469,8 @@ export const fetchAllLocations = withUser(async (user:AuthenticatedUser, year:nu
"bills.payedAmount": 1,
"bills.proofOfPayment.uploadedAt": 1,
"seenByTenantAt": 1,
"tenantEmail": 1,
"tenantEmailStatus": 1,
// "bills.attachment": 0,
// "bills.notes": 0,
// "bills.hub3aText": 1,

14
web-app/app/lib/db-types.ts
View File

@@ -1,3 +1,4 @@
import { unsubscribe } from "diagnostics_channel";
export interface FileAttachment {
fileName: string;
@@ -35,6 +36,17 @@ export interface UserSettings {
ownerRevolutProfileName?: string | null;
};
export enum EmailStatus {
/** Email is not yet verified - recipient has not yet confirmed their email address */
Unverified = "unverified",
/** Email is not yet verified - a verification request has been sent */
VerificationPending = "verification-pending",
/** Email is verified and is in good standing: emails are being successfully delivered */
Verified = "verified",
/** Recepient has unsubscribed from receiving emails via link - no further emails will be sent */
Unsubscribed = "unsubscribed"
}
/** bill object in the form returned by MongoDB */
export interface BillingLocation {
_id: string;
@@ -67,6 +79,8 @@ export interface BillingLocation {
autoBillFwd?: boolean | null;
/** (optional) tenant email */
tenantEmail?: string | null;
/** (optional) tenant email status */
tenantEmailStatus?: EmailStatus | null;
/** (optional) bill forwarding strategy */
billFwdStrategy?: "when-payed" | "when-attached" | null;
/** (optional) whether to automatically send rent notification */

2
web-app/app/ui/EnterOrSignInButton.tsx
View File

@@ -15,7 +15,7 @@ export const EnterOrSignInButton: FC<{ session: any, locale: string, providers:
return (
<>
{
!session ? (
session ? (
<span className="flex justify-center mt-4">
<Link

2
web-app/app/ui/InfoBox.tsx
View File

@@ -17,7 +17,7 @@ export const InfoBox: FC<{
<span className="ml-2 text-sm text-gray-500 group-open:hidden"><ChevronDownIcon className="w-5 h-5 inline" /></span>
<span className="ml-2 text-sm text-gray-500 hidden group-open:inline"><ChevronUpIcon className="w-5 h-5 inline" /></span>
</summary>
<div className="mt-2 italic text-sm text-gray-400 group-open:animate-[animateDown_0.2s_linear_forwards]">{children}</div>
<div className="mt-2 italic text-sm text-gray-400 group-open:animate-[animateDown_0.2s_linear_forwards] max-w-[30rem]">{children}</div>
</details>
)
}

27
web-app/app/ui/LocationCard.tsx
View File

@@ -1,9 +1,9 @@
'use client';
import { CheckCircleIcon, Cog8ToothIcon, PlusCircleIcon, ShareIcon, BanknotesIcon, EyeIcon, TicketIcon, ShoppingCartIcon } from "@heroicons/react/24/outline";
import { CheckCircleIcon, Cog8ToothIcon, PlusCircleIcon, ShareIcon, BanknotesIcon, EyeIcon, TicketIcon, ShoppingCartIcon, EnvelopeIcon, ExclamationTriangleIcon, ClockIcon } from "@heroicons/react/24/outline";
import { FC } from "react";
import { BillBadge } from "./BillBadge";
import { BillingLocation } from "../lib/db-types";
import { BillingLocation, EmailStatus } from "../lib/db-types";
import { formatYearMonth } from "../lib/format";
import { formatCurrency } from "../lib/formatStrings";
import Link from "next/link";
@@ -25,10 +25,11 @@ export const LocationCard: FC<LocationCardProps> = ({ location, currency }) => {
seenByTenantAt,
// NOTE: only the fileName is projected from the DB to reduce data transfer
utilBillsProofOfPayment,
tenantEmail,
tenantEmailStatus,
} = location;
const t = useTranslations("home-page.location-card");
const currentLocale = useLocale();
// sum all the unpaid and paid bill amounts (regardless of who pays)
const totalUnpaid = bills.reduce((acc, bill) => !bill.paid ? acc + (bill.payedAmount ?? 0) : acc, 0);
@@ -69,7 +70,7 @@ export const LocationCard: FC<LocationCardProps> = ({ location, currency }) => {
</Link>
<ShareIcon className="h-[1em] w-[1em] cursor-pointer text-2xl inline hover:text-red-500" title="create sharable link" onClick={handleCopyLinkClick} />
</div>
{ totalUnpaid > 0 || totalPayed > 0 || seenByTenantAt || utilBillsProofOfPayment?.uploadedAt ?
{ totalUnpaid > 0 || totalPayed > 0 || seenByTenantAt || utilBillsProofOfPayment?.uploadedAt || (tenantEmail && tenantEmailStatus && tenantEmailStatus !== EmailStatus.Verified) ?
<>
<div className="flex ml-1">
<div className="divider divider-horizontal p-0 m-0"></div>
@@ -95,6 +96,24 @@ export const LocationCard: FC<LocationCardProps> = ({ location, currency }) => {
</div>
: null
}
{tenantEmail && tenantEmailStatus && tenantEmailStatus !== EmailStatus.Verified && (
<div className="flex ml-1">
<span className="w-5 min-w-5 mr-2">
{tenantEmailStatus === EmailStatus.Unverified && <ExclamationTriangleIcon className="mt-[.1rem] text-warning" />}
{tenantEmailStatus === EmailStatus.VerificationPending && <ClockIcon className="mt-[.1rem] text-info" />}
{tenantEmailStatus === EmailStatus.Unsubscribed && <EnvelopeIcon className="mt-[.1rem] text-error" />}
</span>
<span className={
tenantEmailStatus === EmailStatus.Unverified ? "text-warning" :
tenantEmailStatus === EmailStatus.VerificationPending ? "text-info" :
"text-error"
}>
{tenantEmailStatus === EmailStatus.Unverified && `${t("email-status.unverified")}`}
{tenantEmailStatus === EmailStatus.VerificationPending && `${t("email-status.verification-pending")}`}
{tenantEmailStatus === EmailStatus.Unsubscribed && `${t("email-status.unsubscribed")}`}
</span>
</div>
)}
{seenByTenantAt && (
<div className="flex mt-1 ml-1">
<span className="w-5 mr-2 min-w-5"><EyeIcon className="mt-[.1rem]" /></span>

59
web-app/app/ui/LocationEditForm.tsx
View File

@@ -1,8 +1,8 @@
"use client";
import { TrashIcon } from "@heroicons/react/24/outline";
import { TrashIcon, ExclamationTriangleIcon, ClockIcon, EnvelopeIcon, CheckCircleIcon, PencilSquareIcon } from "@heroicons/react/24/outline";
import { FC, useState } from "react";
import { BillingLocation, UserSettings, YearMonth } from "../lib/db-types";
import { BillingLocation, UserSettings, YearMonth, EmailStatus } from "../lib/db-types";
import { updateOrAddLocation } from "../lib/actions/locationActions";
import { useFormState } from "react-dom";
import Link from "next/link";
@@ -41,6 +41,7 @@ export const LocationEditForm: FC<LocationEditFormProps> = ({ location, yearMont
tenantStreet: location?.tenantStreet ?? "",
tenantTown: location?.tenantTown ?? "",
tenantEmail: location?.tenantEmail ?? "",
tenantEmailStatus: location?.tenantEmailStatus ?? EmailStatus.Unverified,
tenantPaymentMethod: location?.tenantPaymentMethod ?? "none",
proofOfPaymentType: location?.proofOfPaymentType ?? "none",
autoBillFwd: location?.autoBillFwd ?? false,
@@ -50,10 +51,21 @@ export const LocationEditForm: FC<LocationEditFormProps> = ({ location, yearMont
rentDueDay: location?.rentDueDay ?? 1,
});
// tenant e-mail fetched from database
const [dbTenantEmail, setDbTenantEmail] = useState(location?.tenantEmail ?? "");
const handleInputChange = (field: keyof typeof formValues, value: string | boolean | number) => {
setFormValues(prev => ({ ...prev, [field]: value }));
};
const handleResetEmailStatus = () => {
// this will simulate that the email
// is new and needs verification
setDbTenantEmail("");
// reset the email status to unverified
setFormValues(prev => ({ ...prev, tenantEmailStatus: EmailStatus.Unverified }));
};
let { year, month } = location ? location.yearMonth : yearMonth;
return (
@@ -265,7 +277,6 @@ export const LocationEditForm: FC<LocationEditFormProps> = ({ location, yearMont
<fieldset className="fieldset">
<label className="label cursor-pointer justify-start gap-3">
<input
disabled={true}
type="checkbox"
name="autoBillFwd"
className="toggle toggle-primary"
@@ -294,7 +305,6 @@ export const LocationEditForm: FC<LocationEditFormProps> = ({ location, yearMont
<fieldset className="fieldset">
<label className="label cursor-pointer justify-start gap-3">
<input
disabled={true}
type="checkbox"
name="rentDueNotification"
className="toggle toggle-primary"
@@ -357,6 +367,47 @@ export const LocationEditForm: FC<LocationEditFormProps> = ({ location, yearMont
defaultValue={formValues.tenantEmail}
onChange={(e) => handleInputChange("tenantEmail", e.target.value)}
/>
<input
id="tenantEmailStatus"
name="tenantEmailStatus"
type="hidden"
maxLength={30}
defaultValue={formValues.tenantEmailStatus}
/>
{dbTenantEmail === formValues.tenantEmail ? (
<div className="flex items-center gap-2 mt-2 ml-2">
{location?.tenantEmailStatus === EmailStatus.Unverified && (
<>
<ExclamationTriangleIcon className="h-5 w-5 text-warning" />
<span className="text-sm text-warning">{t("email-status.unverified")}</span>
</>
)}
{location?.tenantEmailStatus === EmailStatus.VerificationPending && (
<>
<ClockIcon className="h-5 w-5 text-info" />
<span className="text-sm text-info">{t("email-status.verification-pending")}</span>
</>
)}
{location?.tenantEmailStatus === EmailStatus.Verified && (
<>
<CheckCircleIcon className="h-5 w-5 text-success" />
<span className="text-sm text-success">{t("email-status.verified")}</span>
</>
)}
{location?.tenantEmailStatus === EmailStatus.Unsubscribed && (
<>
<EnvelopeIcon className="h-5 w-5 text-error" />
<span className="text-sm text-error">{t("email-status.unsubscribed")}</span>
<button className="btn btn-neutral min-h-0 h-[1.5rem]" onClick={ handleResetEmailStatus }>{t("email-status.reset-button-label")}</button>
</>
)}
</div>
):(
<div className="flex items-center gap-2 mt-2 ml-2">
<PencilSquareIcon className="h-5 w-5 text-primary" />
<span className="text-sm text-primary">{t("email-status.new")}</span>
</div>
)}
<div id="tenantEmail-error" aria-live="polite" aria-atomic="true">
{state.errors?.tenantEmail &&
state.errors.tenantEmail.map((error: string) => (

81
web-app/messages/en.json
View File

@@ -61,6 +61,11 @@
"monthly-statement-legend": "Monthly statement",
"seen-by-tenant-label": "seen by tenant",
"download-proof-of-payment-label": "proof-of-payment.PDF",
"email-status": {
"unverified": "tenant email not verified",
"verification-pending": "waiting for tenant to verify email",
"unsubscribed": "tenant unsubscribed from receiving emails"
},
"payment-info-header": "You can pay the utility bills for this month using the following information:",
"payment-amount-label": "Amount:",
"payment-recipient-label": "Recipient:",
@@ -86,7 +91,7 @@
"barcodes-found": "barcodes found",
"barcode-singular": "barcode found",
"print-button": "Print Barcodes",
"print-footer": "Generated on {date} • Evidencija Režija Print System",
"print-footer": "Generated on {date} • rezije.app Print System",
"table-header-index": "#",
"table-header-bill-info": "Bill Information",
"table-header-barcode": "2D Barcode",
@@ -190,6 +195,14 @@
"rent-amount-placeholder": "enter rent amount",
"tenant-email-legend": "TENANT EMAIL",
"tenant-email-placeholder": "enter tenant's email",
"email-status": {
"reset-button-label": "Reset",
"new": "a new e-mail address will need to be verified by the tenant",
"unverified": "this e-mail address will need to be verified by the tenant",
"verification-pending": "waiting for tenant to verify this email address",
"verified": "this e-mail address has been verified",
"unsubscribed": "tenant unsubscribed this address from receiving emails"
},
"warning-missing-tenant-names": "Warning: Tenant first and last name are missing. The 2D barcode will not be displayed to the tenant when they open the shared link until both fields are filled in.",
"save-button": "Save",
"cancel-button": "Cancel",
@@ -415,6 +428,72 @@
"content": "If you have any questions about these Terms, please contact us at <emailLink>support@rezije.app</emailLink>."
}
},
"email-verify-page": {
"title": "Verify Your Email Address",
"about": {
"title": "About rezije.app",
"description": "rezije.app is a utility bills tracking application that helps landlords manage their properties and notify tenants about rent and utility bills."
},
"why": {
"title": "Why did you receive this email?",
"description": "Your landlord has configured the application to send rent due and/or utility bills notifications to your email address. To start receiving these notifications, you need to verify your email address."
},
"what-happens": {
"title": "What happens after verification?",
"description": "After you verify your email address, you will receive notifications when rent is due and/or when utility bills are ready, depending on your landlord's configuration. Notifications are sent up to twice per month."
},
"opt-out": {
"title": "Don't want to receive emails?",
"description": "You can ignore this email if you don't want to receive notifications. You can also unsubscribe at any time using the link included in every notification email."
},
"button": {
"verify": "Verify Email Address",
"verifying": "Verifying..."
},
"success": {
"title": "Email Verified!",
"message": "Your email address has been successfully verified. You are now subscribed to receive notifications related to rent and/or utility bills."
},
"error": {
"title": "Verification Failed",
"unknown": "An error occurred during verification. Please try again or contact your landlord."
},
"not-allowed": {
"title": "Action not possible",
"message": "The selected action cannot be performed or the passed information is invalid."
}
},
"email-unsubscribe-page": {
"title": "Unsubscribe from Email Notifications",
"about": {
"title": "About rezije.app",
"description": "rezije.app is a utility bills tracking application that helps landlords manage their properties and notify tenants about rent and utility bills."
},
"why": {
"title": "Why are you receiving emails?",
"description": "Your landlord has configured the application to send rent due and/or utility bills notifications to your email address."
},
"what-happens": {
"title": "What happens after unsubscribing?",
"description": "After you unsubscribe, you will no longer receive any rent due or utility bill notifications via email. Your landlord will need to contact you through other means."
},
"button": {
"unsubscribe": "Confirm Unsubscribe",
"unsubscribing": "Unsubscribing..."
},
"success": {
"title": "Successfully Unsubscribed",
"message": "You have been unsubscribed from email notifications. You will no longer receive rent or utility bill reminders."
},
"error": {
"title": "Unsubscribe Failed",
"unknown": "An error occurred while unsubscribing. Please try again or contact your landlord."
},
"not-allowed": {
"title": "Action not possible",
"message": "The selected action cannot be performed or the passed information is invalid."
}
},
"privacy-policy-page": {
"title": "Privacy Policy for the Utility Bill Tracking Web App",
"meta": {

79
web-app/messages/hr.json
View File

@@ -61,6 +61,11 @@
"monthly-statement-legend": "Obračun",
"seen-by-tenant-label": "viđeno od strane podstanara",
"download-proof-of-payment-label": "potvrda-o-uplati.PDF",
"email-status": {
"unverified": "e-mail podstanara nije potvrđen",
"verification-pending": "čeka se da podstanar potvrdi e-mail",
"unsubscribed": "podstanar odjavio e-mail adresu"
},
"payment-info-header": "Režije za ovaj mjesec možete uplatiti koristeći slijedeće podatke:",
"payment-amount-label": "Iznos:",
"payment-recipient-label": "Primatelj:",
@@ -189,6 +194,14 @@
"rent-amount-placeholder": "unesite iznos najamnine",
"tenant-email-legend": "EMAIL PODSTANARA",
"tenant-email-placeholder": "unesite email podstanara",
"email-status": {
"reset-button-label": "Reset",
"new": "nova e-mail adresa - podstanar će je morati potvrditi",
"unverified": "čeka se da podstanar potvrdi e-mail",
"verification-pending": "čeka se da podstanar potvrdi e-mail",
"verified": "podstanar je potvrdio ovu e-mail adresu",
"unsubscribed": "podstanar je odjavio ovu e-mail adresu"
},
"warning-missing-tenant-names": "Upozorenje: Ime i prezime podstanara nedostaju. 2D barkod neće biti prikazan podstanaru kada otvori podijeljenu poveznicu dok oba polja ne budu popunjena.",
"save-button": "Spremi",
"cancel-button": "Odbaci",
@@ -412,6 +425,72 @@
"content": "Ako imate bilo kakvih pitanja o ovim Uvjetima, kontaktirajte nas na <emailLink>support@rezije.app</emailLink>."
}
},
"email-verify-page": {
"title": "Potvrdite Vašu Email Adresu",
"about": {
"title": "O aplikaciji rezije.app",
"description": "rezije.app je aplikacija za praćenje režija koja pomaže vlasnicicama nekretnina da upravljaju svojim objektima i obavještavaju zakupce o dospjeloj najamnini i režijama."
},
"why": {
"title": "Zašto ste primili ovaj email?",
"description": "Vaš vlasnik nekretnine je konfigurirao aplikaciju da šalje obavijesti o dospjeloj najamnini i/ili režijama na vašu email adresu. Da biste počeli primati ove obavijesti, trebate potvrditi svoju email adresu."
},
"what-happens": {
"title": "Što se događa nakon potvrde?",
"description": "Nakon što potvrdite svoju email adresu, početi ćete primate obavijesti kada najamnina dospije i/ili kada su režije spremne, ovisno o konfiguraciji vašeg vlasnika nekretnine. Obavijesti se šalju do dva puta mjesečno."
},
"opt-out": {
"title": "Ne želite primati emailove?",
"description": "Možete zanemariti ovaj email ako ne želite primati obavijesti. Također se možete odjaviti u bilo kojem trenutku putem linka koji će biti uključen u svakom emailu koji primite."
},
"button": {
"verify": "Potvrdi Email Adresu",
"verifying": "Potvrđivanje..."
},
"success": {
"title": "Email Potvrđen!",
"message": "Vaša email adresa je uspješno potvrđena. Sada ste pretplaćeni na obavijesti vezane za najamninu i/ili režije."
},
"error": {
"title": "Potvrda Nije Uspjela",
"unknown": "Došlo je do greške prilikom potvrde. Molimo pokušajte ponovno ili kontaktirajte vašeg vlasnika nekretnine."
},
"not-allowed": {
"title": "Akcija nije moguća",
"message": "Odabrana akcija nije moguća ili zadani podaci nisu ispravni."
}
},
"email-unsubscribe-page": {
"title": "Obavjesti o režijama - Odjava",
"about": {
"title": "O aplikaciji rezije.app",
"description": "rezije.app je aplikacija za praćenje režija koja pomaže vlasnicicama nekretnina da upravljaju svojim objektima i obavještavaju zakupce o dospjeloj najamnini i režijama."
},
"why": {
"title": "Zašto primate emailove?",
"description": "Vaš vlasnik nekretnine je konfigurirao aplikaciju da šalje obavijesti o dospjeloj najamnini i/ili režijama na vašu email adresu."
},
"what-happens": {
"title": "Što se događa nakon odjave?",
"description": "Nakon što se odjavite, više nećete primati nikakve obavijesti o dospjeloj najamnini ili režijama putem emaila. Vaš vlasnik nekretnine će vas morati kontaktirati drugim putem."
},
"button": {
"unsubscribe": "Potvrdi Odjavu",
"unsubscribing": "Odjava u tijeku..."
},
"success": {
"title": "Uspješno Odjavljeni",
"message": "Odjavljeni ste od email obavijesti. Više nećete primati obavijesti o najamnini ili režijama."
},
"error": {
"title": "Odjava Nije Uspjela",
"unknown": "Došlo je do greške prilikom odjave. Molimo pokušajte ponovno ili kontaktirajte vašeg vlasnika nekretnine."
},
"not-allowed": {
"title": "Akcija nije moguća",
"message": "Odabrana akcija nije moguća ili zadani podaci nisu ispravni."
}
},
"privacy-policy-page": {
"title": "Politika privatnosti za web aplikaciju za evidenciju režija",
"meta": {