Merge branch 'main' into feature/multi-currency-price-feed

Author: elizabetheonoja-art

.env.example

@@ -0,0 +1,61 @@
+# Server Config
+PORT=3000
+
+# IPFS Config (Example using Infura)
+IPFS_HOST=ipfs.infura.io
+IPFS_PORT=5001
+IPFS_PROTOCOL=https
+IPFS_PROJECT_ID=your_infura_project_id
+IPFS_PROJECT_SECRET=your_infura_project_secret
+
+# Stellar Config
+CONTRACT_ID=CAEGD57WVTVQSYWYB23AISBW334QO7WNA5XQ56S45GH6BP3D2AVHKUG4
+PORT=3000
+
+# Auth configuration
+AUTH_JWT_SECRET=replace-with-a-long-random-secret
+AUTH_JWT_ISSUER=leaseflow-backend
+AUTH_JWT_AUDIENCE=leaseflow-users
+
+# SQLite persistence
+DATABASE_FILENAME=./data/leaseflow-protocol.sqlite
+
+# Lease renewal job
+LEASE_RENEWAL_JOB_ENABLED=false
+LEASE_RENEWAL_JOB_INTERVAL_MS=86400000
+LEASE_RENEWAL_SCAN_WINDOW_DAYS=0
+
+# Soroban configuration
+SOROBAN_CONTRACT_ID=CAEGD57WVTVQSYWYB23AISBW334QO7WNA5XQ56S45GH6BP3D2AVHKUG4
+DISCORD_WEBHOOK_URL=your_discord_webhook_url_here
+# Algorand Configuration
+# Algorand Network Configuration
+ALGOD_TOKEN=
+ALGOD_SERVER=https://testnet-api.algonode.cloud
+ALGOD_PORT=443
+
+# PostgreSQL Database Configuration
+DATABASE_URL=postgresql://username:password@localhost:5432/leaseflow_db
+# OR use individual variables:
+# DB_HOST=localhost
+# DB_PORT=5432
+# DB_NAME=leaseflow_db
+# DB_USER=username
+# DB_PASSWORD=password
+
+# Email Configuration (for notifications)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=your-email@gmail.com
+SMTP_PASS=your-app-password
+EMAIL_FROM=your-email@gmail.com
+
+# SMS Configuration (Twilio)
+TWILIO_ACCOUNT_SID=your-twilio-account-sid
+TWILIO_AUTH_TOKEN=your-twilio-auth-token
+TWILIO_PHONE_NUMBER=+1234567890
+
+# Owner Configuration (for auto-reclaim)
+# Owner Account (for executing reclaim transactions)
+OWNER_MNEMONIC=

.gitignore

@@ -1,2 +1,3 @@
 node_modules
 .env
+data

docs/features/LEASE_RENEWAL_OPTION_GENERATOR.md

@@ -0,0 +1,89 @@
+# Lease Renewal Option Generator
+
+## Overview
+
+This feature adds an automated backend workflow that scans active leases approaching expiry, generates renewal proposals from landlord-defined rules, notifies both parties, and prepares the next Soroban lease contract payload after mutual acceptance.
+
+## 60-Day Scan Behavior
+
+- The renewal scan runs through `LeaseRenewalJob`.
+- The job evaluates active, renewable, non-disputed leases.
+- By default, a lease is eligible when it is exactly `notice_days` away from expiry.
+- `LEASE_RENEWAL_SCAN_WINDOW_DAYS` can widen the lower bound if operations want a small grace window.
+
+## Renewal Rule Application
+
+Each landlord can define one renewal rule with:
+
+- `increase_type`: `percentage`, `fixed`, or `same`
+- `increase_value`
+- `term_months`
+- `notice_days`
+- `enabled`
+
+The backend computes proposed terms on the server. Clients do not supply new rent or renewal dates.
+
+## Duplicate Prevention / Idempotency
+
+- Renewal proposals are keyed by `lease_id + target_start_date`.
+- The scan checks for an existing proposal for the same renewal cycle before generating a new one.
+- Re-running the job for the same day is safe and does not create duplicates.
+
+## Notification Flow
+
+When a proposal is generated, the backend persists one notification for:
+
+- the landlord
+- the tenant
+
+Each notification includes the lease reference, proposal reference, and a concise summary message.
+
+## Agreement Flow
+
+Available routes:
+
+- `GET /renewal-proposals/:proposalId`
+- `POST /renewal-proposals/:proposalId/accept`
+- `POST /renewal-proposals/:proposalId/reject`
+
+Only the proposal's landlord or tenant can view or act on it.
+
+Status progression:
+
+- `generated`
+- `landlord_accepted`
+- `tenant_accepted`
+- `fully_accepted`
+- `contract_prepared`
+- `rejected`
+- `expired`
+
+## Soroban Contract Preparation
+
+Once both parties accept:
+
+- the backend prepares the next Soroban lease contract reference
+- the proposal is marked `contract_prepared` when successful
+- if preparation fails, the proposal remains `fully_accepted` and `soroban_contract_status` becomes `failed`
+
+Tests mock Soroban behavior and do not require a live network.
+
+## Scheduling Notes
+
+- Enable automatic scheduling with `LEASE_RENEWAL_JOB_ENABLED=true`.
+- The interval is configured with `LEASE_RENEWAL_JOB_INTERVAL_MS`.
+- The default interval is once every 24 hours.
+
+## Security Considerations
+
+- Proposal ownership is enforced by signed bearer tokens and lease participant checks.
+- Landlords and tenants can only act on proposals tied to their own lease.
+- Renewal terms are server-generated from stored rules.
+- Duplicate generation is prevented for the same lease cycle.
+- Mutual acceptance is required before Soroban preparation.
+
+## Limitations / Future Extensions
+
+- The repository did not include an existing DB, notification bus, scheduler, or Soroban deployment stack, so this feature adds a focused SQLite-backed implementation and an injectable Soroban preparation service.
+- Automatic expiration sweeps can be added later if proposal expiry needs active enforcement.
+- If the project adopts a richer auth or job platform later, the current services provide clear seams for integration.