Merge pull request #69 from Ahbiz/feature/non-custodial-refunds feat(stellar): implement non-custodial refund and dispute flow (#62)

.env.example

@@ -26,6 +26,11 @@ EMAILJS_SERVICE_ID=your_service_id
 EMAILJS_TEMPLATE_ID=your_template_id
 
 # Stellar blockchain network (testnet or mainnet)
+EMAILJS_PRIVATE_KEY=your_emailjs_private_key
+EMAILJS_PUBLIC_KEY=your_emailjs_public_key
+EMAILJS_SERVICE_ID=your_emailjs_service_id
+EMAILJS_TEMPLATE_ID=your_emailjs_template_id
+EMAILJS_RECEIPT_TEMPLATE_ID=your_emailjs_receipt_template_id
 STELLAR_NETWORK=testnet
 
 # Resilient Horizon Client Configuration (Optional)
@@ -42,6 +47,17 @@ DONATION_WALLET_PUBLIC_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 PLATFORM_FEE_PERCENT=0
 PLATFORM_WALLET_PUBLIC_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
+# SEP-1 stellar.toml (/.well-known/stellar.toml) — optional, omitted when blank
+STELLAR_PLATFORM_PUBLIC_KEY=
+ORG_NAME=
+ORG_URL=
+ORG_DESCRIPTION=
+ORG_LOGO=
+ORG_TWITTER=
+ORG_GITHUB=
+# SEP-10 signing key (leave blank until #25 is implemented)
+SIGNING_KEY=
+
 # Token TTLs
 ACCESS_TOKEN_TTL=15m
 REFRESH_TOKEN_TTL=30d
@@ -63,3 +79,8 @@ REDIS_PORT=6379
 # JITSI_PUBLIC_KEY_ID=your_public_key_id
 # JITSI_KID=your_kid
 # JITSI_TENANT=your_tenant
+# Durable Mongo-backed background jobs (tests use inline)
+JOBS_ENABLED=true
+QUEUE_DRIVER=mongo
+JOBS_DASHBOARD_TOKEN=replace_with_a_long_random_token
+

.github/workflows/ci.yml

@@ -38,6 +38,9 @@ jobs:
           MONGO_URI: mongodb://localhost:27017/deenbridge_test
           JWT_SECRET: test-secret-key-for-ci-minimum-32-chars
           STELLAR_NETWORK: testnet
+          CLOUDINARY_CLOUD_NAME: ci_test_cloud
+          CLOUDINARY_API_KEY: ci_test_key
+          CLOUDINARY_API_SECRET: ci_test_secret_that_should_not_leak
 
   build:
     name: Syntax and Boot Check
@@ -88,3 +91,6 @@ jobs:
           MONGO_URI: mongodb://localhost:27017/deenbridge_boot
           JWT_SECRET: test-secret-key-for-ci-minimum-32-chars
           STELLAR_NETWORK: testnet
+          CLOUDINARY_CLOUD_NAME: ci_test_cloud
+          CLOUDINARY_API_KEY: ci_test_key
+          CLOUDINARY_API_SECRET: ci_test_secret_that_should_not_leak

.gitignore

@@ -1,27 +1,36 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Dependency directories
-node_modules/
-jspm_packages/
-
-# Environment variables
-.env
-
-# Build output
-dist/
-build/
-
-# IDE files
-.vscode/
-.DS_Store
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Environment variables
+.env
+.env.test
+
+# Build output
+dist/
+build/
+
+# IDE files
+.vscode/
+.DS_Store
+
+# Spec & Agent temporary docs
+Tasks.md
+Memory.md
+Handoff.md
+PRD.md
+Architecture.md
+scratch/

QUICK_START.md

@@ -62,6 +62,18 @@ curl -X POST http://localhost:5000/api/auth/login \
 
 ---
 
+## 🌐 **Stellar TOML (SEP-1)**
+
+The API serves ecosystem metadata at `/.well-known/stellar.toml`:
+
+```bash
+curl http://localhost:5000/.well-known/stellar.toml
+```
+
+Optional env vars for the TOML: `STELLAR_PLATFORM_PUBLIC_KEY`, `ORG_NAME`, `ORG_URL`, `ORG_DESCRIPTION`, `ORG_LOGO`, `ORG_TWITTER`, `ORG_GITHUB`. (`SIGNING_KEY` is a placeholder that must remain unset until SEP-10 #25). See `.env.example`.
+
+---
+
 ## 🔍 **Monitor Logs**
 
 ```bash

README.md

@@ -78,9 +78,23 @@ The API runs at `http://localhost:5000`.
 | `JWT_SECRET` | Secret for signing tokens (32+ chars) |
 | `STELLAR_NETWORK` | `testnet` or `mainnet` |
 | `CLOUDINARY_*` | Cloudinary credentials for media uploads |
+| `QUEUE_DRIVER` | `mongo` (durable production default) or `inline` (tests/CI) |
+| `JOBS_ENABLED` | Start background workers; defaults to `true` |
+| `JOBS_DASHBOARD_TOKEN` | Bearer token protecting `/admin/jobs` |
+| `STELLAR_PLATFORM_PUBLIC_KEY` | Public key published in `stellar.toml` `ACCOUNTS[]` |
 
 See `.env.example` for the full list.
 
+### Background jobs
+
+Slow email and Stellar verification work uses the thin `src/jobs/queue.js`
+abstraction. The production `mongo` driver persists jobs in the mandatory
+MongoDB deployment, so work and idempotency keys survive restarts without
+making optional Redis a new requirement. The `inline` driver uses the same
+handlers in tests and CI. Jobs retry with exponential backoff and jitter,
+terminal failures are queryable at `/admin/jobs/dead`, and the token-protected
+dashboard is available at `/admin/jobs`.
+
 ### Scripts
 
 | Command | Purpose |
@@ -94,6 +108,7 @@ See `.env.example` for the full list.
 
 | Area | Base Route |
 |------|-----------|
+| SEP-1 Metadata | `/.well-known/stellar.toml` |
 | Auth & Users | `/api/auth`, `/api/users` |
 | Courses & Books | `/api/courses`, `/api/books` |
 | Spaces & Reels | `/api/spaces`, `/api/reels` |

app.js

@@ -4,6 +4,7 @@ import cookieParser from "cookie-parser";
 import compression from "compression";
 import dotenv from "dotenv";
 import crypto from "crypto";
+import "./src/jobs/handlers.js";
 
 dotenv.config();
 
@@ -43,6 +44,9 @@ import stellarWalletRoutes from "./src/routes/stellar/walletRoutes.js";
 import stellarPaymentRoutes from "./src/routes/stellar/paymentRoutes.js";
 import stellarDonationRoutes from "./src/routes/stellar/donationRoutes.js";
 import payoutRoutes from "./src/routes/payoutRoutes.js";
+import uploadRoutes from "./src/routes/uploadRoutes.js";
+import jobsRoutes from "./src/routes/jobsRoutes.js";
+import wellKnownRoutes from "./src/routes/wellKnownRoutes.js";
 
 handleUncaughtException();
 validateEnv();
@@ -159,6 +163,9 @@ app.get("/health", (req, res) => {
   });
 });
 
+// SEP-1 stellar.toml — must be outside /api rate limiter
+app.use("/.well-known", wellKnownRoutes);
+
 app.use("/api", apiLimiter);
 
 // Auth routes
@@ -179,6 +186,8 @@ app.use("/api/stellar/wallet", stellarWalletRoutes);
 app.use("/api/stellar/payment", stellarPaymentRoutes);
 app.use("/api/stellar/donation", stellarDonationRoutes);
 app.use("/api/payouts", payoutRoutes);
+app.use("/api/uploads", uploadRoutes);
+app.use("/admin/jobs", jobsRoutes);
 
 // ======================
 // ERROR HANDLING

docs/caching.md

@@ -0,0 +1,75 @@
+# Redis Caching
+
+This documents which endpoints are cached, their TTLs, and the invalidation
+strategy. The underlying helpers live in `src/utils/cache.js` (Redis
+primitives, `CACHE_TTL`/`CACHE_KEYS` presets) and `src/middlewares/cache.js`
+(`cacheMiddleware`, `smartCache`, `invalidateCacheMiddleware`).
+
+All caching degrades gracefully: `getCache`/`setCache`/`deleteCachePattern`
+check `isRedisReady()` first and no-op (falling through to Mongo) when Redis
+is unavailable, so a down Redis instance never breaks a request.
+
+## Cached read endpoints
+
+| Endpoint | Cache key | TTL | Notes |
+|---|---|---|---|
+| `GET /api/books` | `books:list` | 15 min (`CACHE_TTL.BOOKS`) |  |
+| `GET /api/books/:id` | `book:<id>` | 15 min |  |
+| `GET /api/books/by-author/:authorId` | `books:author:<authorId>` | 15 min |  |
+| `GET /api/books/recom` | `books:recommended` | 3 min (`CACHE_TTL.SHORT`) | shared key regardless of `interests`; the controller (`fetchRecommendedBooks`) also has a pre-existing bug (undefined `category` reference) that makes it non-functional today - out of scope here |
+| `POST /api/books/recommended` | `books:recommended:<sorted interests \| "popular">` | 15 min (`CACHE_TTL.BOOKS`) | added in this change; keyed explicitly in the controller since `cacheMiddleware` only intercepts GET |
+| `GET /api/courses` | `courses:list` | 15 min (`CACHE_TTL.COURSES`) |  |
+| `GET /api/courses/:id` | `course:<id>` | 15 min |  |
+| `GET /api/courses/user` | `courses:user:<createdBy>` | 15 min |  |
+| `POST /api/courses/recommended` | `courses:recommended:<sorted interests \| "none">` | 15 min (`CACHE_TTL.COURSES`) | added in this change; previously explicitly left uncached ("POST routes not cached") |
+| `GET /api/spaces` | `spaces:list` | 5 min (`CACHE_TTL.SPACES`) |  |
+| `GET /api/spaces/:id` | `space:<id>` | 5 min |  |
+| `GET /api/spaces/by-host/:hostId` | `spaces:host:<hostId>` | 5 min |  |
+| `GET /api/search` | `search:<type>:<q>` | 5 min (`CACHE_TTL.SEARCH`) |  |
+| `GET /api/users/:id` | `user:<id>` | 10 min (`CACHE_TTL.USERS`) |  |
+| `GET /api/users/recommendations` | `user:<requester id>:recommendations` | 10 min | keyed per requesting user |
+| `GET /api/users/:userId/followers` | `user:<userId>:followers` | 10 min |  |
+| `GET /api/users/:userId/following` | `user:<userId>:following` | 10 min |  |
+
+The books/courses/spaces/search/users list and detail endpoints above were
+wired up separately (see `feat: configure Redis cache layer for production
+use`, merged to `main`). This change adds the two `POST /recommended`
+entries, which that work left uncached, plus this document.
+
+## Invalidation
+
+Writes call `invalidateCacheMiddleware` with wildcard patterns so a create,
+update, delete, or review clears the relevant cached list/detail entries
+(`deleteCachePattern` runs a Redis `KEYS` scan against the pattern):
+
+- Books: `createBook` invalidates `books:*`; `deleteBook` and `addBookReview` invalidate `books:*` and `book:*`.
+- Courses: `createCourse` invalidates `courses:*`; `enrollInCourse`/`addCourseReview` invalidate `course:*`; `updateCourse` invalidates `courses:*` and `course:*`.
+- Spaces: `createSpace` invalidates `spaces:*`; `joinWaitList` invalidates `space:*`; `updateSpace`/`deleteSpace` invalidate `spaces:*` and `space:*`.
+- Users: profile/follow writes invalidate `user:*` (and `user:*:followers` / `user:*:following` on follow/unfollow).
+
+`books:*` and `courses:*` also cover the new `books:recommended:*` /
+`courses:recommended:*` keys added in this change, since they share the same
+prefix - no separate invalidation wiring was needed for them.
+
+Search has no dedicated invalidation hook (it spans five collections); its
+5-minute TTL is the staleness bound instead.
+
+## Deliberately not cached
+
+- **Bookmarks** (`GET /api/books/bookmarks`, `GET /api/courses/bookmarks`,
+  and the `bookmark/check` routes) are per-user and are left uncached rather
+  than risk leaking one user's bookmark state into another user's response
+  under a shared key.
+- **Reels** (`GET /api/reels`, `GET /api/reels/:id`) embed the requesting
+  user's `viewerState` (liked/loved) directly in each reel object. Caching
+  the response as-is would leak one viewer's like/love state to every other
+  viewer who hits the same cache key, so these are left uncached until the
+  response shape separates viewer-specific state from the shared reel data.
+
+## User-specific data
+
+`cacheMiddleware`/`smartCache` support a per-request key generator (and
+`smartCache`'s `includeUser` option) for endpoints that must vary per user -
+see `GET /api/users/recommendations` above, which folds the requester's id
+into the key. Any future authenticated, user-specific GET endpoint should do
+the same rather than caching under a shared key.

jest.config.js

@@ -1,4 +1,5 @@
 export default {
   testEnvironment: "node",
   transform: {},
+  setupFiles: ["<rootDir>/test/jest.setup.js"],
 };