feat(notifications): real-time WebSocket invoice event notifications (#9)

.env.example

@@ -25,6 +25,15 @@ HORIZON_URL=http://localhost:8000
 PORT=4000
 JWT_SECRET=change_me_to_a_strong_random_secret
 
+# Settlement event listener (issue #3). Optional — sane defaults apply.
+# Comma-separated Soroban contract ids to filter events by (default: all).
+INVOICE_CONTRACT_ID=
+# How often the listener polls Soroban RPC for settlement events (ms).
+SETTLEMENT_POLL_INTERVAL_MS=5000
+# Per-event retry attempts and exponential-backoff base delay (ms).
+SETTLEMENT_MAX_ATTEMPTS=3
+SETTLEMENT_RETRY_BASE_MS=500
+
 # ── Frontend ─────────────────────────────────────────────────
 NEXT_PUBLIC_API_URL=http://localhost:4000
 NEXT_PUBLIC_HORIZON_URL=http://localhost:8000

.github/workflows/app-ci.yml

@@ -0,0 +1,54 @@
+name: Backend & Frontend CI
+
+on:
+  push:
+    paths:
+      - "backend/**"
+      - "frontend/**"
+      - ".github/workflows/app-ci.yml"
+  pull_request:
+    paths:
+      - "backend/**"
+      - "frontend/**"
+      - ".github/workflows/app-ci.yml"
+
+jobs:
+  backend:
+    name: Backend Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: backend/package-lock.json
+
+      - run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+  frontend:
+    name: Frontend Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+
+      - name: Run tests
+        run: npm test

.github/workflows/contracts.yml

@@ -0,0 +1,48 @@
+name: Soroban Contracts
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "contracts/**"
+      - ".github/workflows/contracts.yml"
+  pull_request:
+    paths:
+      - "contracts/**"
+      - ".github/workflows/contracts.yml"
+
+defaults:
+  run:
+    working-directory: contracts
+
+jobs:
+  test:
+    name: Format, lint & test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            contracts/target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('contracts/**/Cargo.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Check formatting
+        run: cargo fmt --all --check
+
+      - name: Clippy (warnings as errors)
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Run unit tests
+        run: cargo test --all

backend/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+coverage/
+*.log
+.env
+# Prisma generated client
+src/generated/

backend/README.md

@@ -0,0 +1,80 @@
+# InvoiceFi-Stellar Backend
+
+NestJS + Prisma (PostgreSQL) backend. Its primary job is to keep the off-chain
+invoice records in sync with on-chain state — in particular, transitioning
+invoices to `REPAID` when the settlement contract repays them on-chain (issue
+#3) — and to serve invoice/dashboard data over REST.
+
+## Stack
+
+- **NestJS 11** — HTTP API + scheduled jobs
+- **Prisma 6 / PostgreSQL** — persistence
+- **@stellar/stellar-sdk** — Soroban RPC `getEvents` + XDR decoding
+- **Jest** — unit tests
+
+## Settlement event listener (issue #3)
+
+`src/settlement/` polls Soroban RPC and applies settlements:
+
+- `soroban-events.service.ts` — calls `rpc.Server.getEvents`, decodes each
+  event's XDR topics/value into native values (`NormalizedEvent`).
+- `settlement-event.parser.ts` — pure function that recognizes `InvoiceSettled`
+  events and extracts the invoice id.
+- `settlement.service.ts` — `settleInvoice()` transitions `FUNDED → REPAID` via
+  a single conditional `updateMany` inside a transaction. **Atomic** (guarded on
+  `status = FUNDED`) and **idempotent** (a replayed event for an already-`REPAID`
+  invoice is a no-op).
+- `settlement-sync.service.ts` — polls every `SETTLEMENT_POLL_INTERVAL_MS`
+  (default 5s, so dashboards reflect settlement within ~10s). Each event is
+  settled through `withRetry` (max 3 attempts, exponential backoff). The ledger
+  cursor only advances past fully-processed ledgers, so a permanently-failing
+  event is retried on the next cycle instead of being skipped.
+- `sync-cursor.service.ts` — persists the last processed ledger (`SyncCursor`).
+
+Dashboards read current status via `src/invoices/` REST endpoints:
+
+| Method & path                          | Purpose                          |
+| -------------------------------------- | -------------------------------- |
+| `GET /health`                          | Liveness (used by compose).      |
+| `GET /invoices`                        | All invoices.                    |
+| `GET /invoices/:onchainId`             | Single invoice by on-chain id.   |
+| `GET /dashboard/farmer/:address`       | A farmer's invoices.             |
+| `GET /dashboard/investor/:address`     | An investor's invoices.          |
+
+## Environment
+
+See the repo-root `.env.example`. Key variables: `DATABASE_URL`,
+`STELLAR_RPC_URL`, `PORT`, and optional listener tuning:
+
+| Variable                       | Default | Meaning                                   |
+| ------------------------------ | ------- | ----------------------------------------- |
+| `INVOICE_CONTRACT_ID`          | (all)   | Comma-separated contract ids to filter.   |
+| `SETTLEMENT_POLL_INTERVAL_MS`  | `5000`  | Listener poll interval.                   |
+| `SETTLEMENT_MAX_ATTEMPTS`      | `3`     | Retry attempts per event.                 |
+| `SETTLEMENT_RETRY_BASE_MS`     | `500`   | Backoff base delay.                       |
+
+## Commands
+
+```bash
+npm install
+npm run prisma:generate           # generate Prisma client
+npm test                          # unit tests (no DB/chain needed)
+npm run build                     # tsc -> dist/
+
+# With a live PostgreSQL (DATABASE_URL set):
+npx prisma migrate deploy         # apply migrations
+npm start                         # node dist/main, listens on PORT (4000)
+```
+
+The included migration (`prisma/migrations/00000000000000_init`) was generated
+with `prisma migrate diff`; on a fresh database `prisma migrate deploy` creates
+the `Invoice` and `SyncCursor` tables.
+
+## Tests
+
+Unit tests run fully offline (Prisma and the Soroban RPC are mocked):
+
+- `common/retry.spec.ts` — backoff, attempt cap, last-error propagation.
+- `settlement/settlement-event.parser.spec.ts` — event recognition & id extraction.
+- `settlement/settlement.service.spec.ts` — atomic transition, idempotency, error cases.
+- `settlement/settlement-sync.service.spec.ts` — cursor advancement, retry, fail-and-resume.

backend/jest.config.js

@@ -0,0 +1,11 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  moduleFileExtensions: ['js', 'json', 'ts'],
+  rootDir: 'src',
+  testRegex: '.*\\.spec\\.ts$',
+  transform: {
+    '^.+\\.ts$': ['ts-jest', { tsconfig: '<rootDir>/../tsconfig.json' }],
+  },
+  collectCoverageFrom: ['**/*.(t|j)s'],
+  testEnvironment: 'node',
+};