Wellysa API

Mikroserwis API zastępujący Firebase Functions. Jednolity backend dla serwisów korzystających z Firebase Authentication, obsługujący dwa projekty Firebase (ORAP i ORAM) w jednej instancji.

Stack

• Hono 4.12+ + Zod OpenAPI + Scalar — lekki framework z walidacją i interaktywną dokumentacją
• Firebase Admin SDK 13.7+ — autoryzacja i Firestore (multi-project)
• Stripe 22.1+ — płatności i subskrypcje
• Resend 6.9+ — email transakcyjny
• TypeScript 5.9+ strict, ESNext, ESM
• Bun — runtime + package manager
• Prometheus — metryki aplikacji
• reCAPTCHA — ochrona formularzy
• OpenCV OCR — integracja rozpoznawania tekstu

Szybki start

# Instalacja
bun install

# Konfiguracja
cp .env.example .env
# Uzupełnij FIREBASE_ORAP_SERVICE_ACCOUNT, FIREBASE_ORAM_SERVICE_ACCOUNT i pozostałe zmienne

# Uruchomienie (dev)
bun dev

# Type-check
bun run build

# Produkcja
bun start

# Seed algorytmów
bun run seed:score2
bun run seed:wcrf

Serwer nasłuchuje domyślnie na http://localhost:3000.

Zmienne środowiskowe

Zmienna	Domyślna	Opis
PORT	3000	Port serwera
NODE_ENV	development	production — ukrywa /docs i /openapi.json
FIREBASE_ORAP_SERVICE_ACCOUNT	—	JSON service account dla projektu orap-dev
FIREBASE_ORAM_SERVICE_ACCOUNT	—	JSON service account dla projektu oram-dev
TEST_COVERAGE_PERCENT	0	Metryka pokrycia testami (Prometheus)
README_TOKEN	—	Token chroniący endpoint /readme (puste = publiczny)
RESEND_API_KEY	—	Klucz API Resend (email transakcyjny)
STRIPE_SECRET_KEY	—	Klucz API Stripe
RECAPTCHA_SECRET_KEY	—	Secret key Google reCAPTCHA

Klucze Firebase muszą być w formacie jednoliniowego JSON (bez newlines).

Endpointy

System (bez wersji, bez auth)

Metoda	Ścieżka	Opis
GET	/health	Health check
GET	/metrics	Metryki Prometheus
GET	/readme	Dokumentacja Markdown (opcjonalnie chroniona tokenem)

Tools (bez wersji)

Metoda	Ścieżka	Opis
POST	/tools/auth/firebase	Firebase ID token (tylko dev)
GET	/tools/synevo-services	Lista usług Synevo

Auth (/v1/auth)

Metoda	Ścieżka	Opis
POST	/v1/auth/login	Logowanie (email + hasło)
POST	/v1/auth/verify	Weryfikacja sesji
POST	/v1/auth/logout	Wylogowanie
PUT	/v1/auth/password/change	Zmiana hasła (auth required)
POST	/v1/auth/password/reset	Żądanie resetu hasła
POST	/v1/auth/password/reset/validate	Walidacja tokenu resetu
POST	/v1/auth/password/reset/confirm	Potwierdzenie resetu hasła
POST	/v1/auth/password/reset/code-request	Żądanie kodu weryfikacyjnego (email/SMS)
POST	/v1/auth/password/reset/code-confirm	Potwierdzenie kodu weryfikacyjnego

Codes (/v1/codes, auth required)

Metoda	Ścieżka	Opis
POST	/v1/codes	Tworzenie kodu
GET	/v1/codes/{id}/status	Status kodu
PUT	/v1/codes/{id}	Aktualizacja kodu
DELETE	/v1/codes/{id}	Usunięcie kodu

Products (/v1/products) (w trakcie implementacji — zweryfikuj z zespołem)

Metoda	Ścieżka	Opis
GET	/v1/products	Lista produktów
GET	/v1/products/{id}	Szczegóły produktu
GET	/v1/products/{id}/stripe	Stripe IDs produktu (auth)
GET	/v1/products/{id}/collectionPoints	Punkty pobrań produktu (auth)

Query param ?lang=pl (domyślny), ?lang=en, ?lang=all.

Users (/v1/users) (w trakcie implementacji — zweryfikuj z zespołem)

Metoda	Ścieżka	Opis
GET	/v1/users/me	Dane zalogowanego użytkownika
PUT	/v1/users/me	Aktualizacja własnego profilu
GET	/v1/users	Lista użytkowników (paginacja, search, sort)
POST	/v1/users	Tworzenie użytkownika
GET	/v1/users/{uid}	Szczegóły użytkownika
PUT	/v1/users/{uid}	Aktualizacja użytkownika
DELETE	/v1/users/{uid}	Usunięcie użytkownika
POST	/v1/users/{uid}/reset-password	Reset hasła użytkownika CMS
POST	/v1/users/{uid}/reset-account	Reset konta klienta

Collection Points (/v1/collection-points) (w trakcie implementacji — zweryfikuj z zespołem)

Metoda	Ścieżka	Opis
GET	/v1/collection-points	Lista punktów pobrań
GET	/v1/collection-points/{id}	Szczegóły punktu pobrań
POST	/v1/collection-points	Tworzenie punktu pobrań
PATCH	/v1/collection-points/{id}	Aktualizacja punktu pobrań
DELETE	/v1/collection-points/{id}	Usunięcie punktu pobrań
GET	/v1/collection-points/companies	Lista firm
POST	/v1/collection-points/companies	Tworzenie firmy
PATCH	/v1/collection-points/companies/{id}	Aktualizacja firmy
DELETE	/v1/collection-points/companies/{id}	Usunięcie firmy
POST	/v1/collection-points/companies/replace	Zamiana firmy (migracja punktów)

Algorithms (/v1/algorithms) (w trakcie implementacji — zweryfikuj z zespołem)

Metoda	Ścieżka	Opis
POST	/v1/algorithms/wcrf	Kalkulacja WCRF lifestyle score
POST	/v1/algorithms/score2	Kalkulacja SCORE2 ryzyka sercowo-naczyniowego

Seeding dostępny przez bun run seed:wcrf i bun run seed:score2.

Dokumentacja API

W trybie development:

• Interaktywna dokumentacja: http://localhost:3000/docs (Scalar)
• OpenAPI 3.1 spec: http://localhost:3000/openapi.json

W NODE_ENV=production oba endpointy są wyłączone (404).

Cachowanie

Mechanizm in-memory cache (TTL = 1 godzina) dla optymalizacji zapytań Firestore. Cache przechowuje dane przed transformacją językową — jeden wpis obsługuje wszystkie warianty lang.

Autoryzacja

Firebase Admin SDK z obsługą dwóch projektów:

• ORAP (orap-dev) — produkty, Firestore
• ORAM (oram-dev) — dostępny dla auth

Middleware weryfikuje token w kolejności:

1. Jeśli header X-Firebase-Project ustawiony → weryfikuje tylko tym projektem
2. Bez hinta → próbuje ORAP, potem ORAM (fallback)

Inicjalizacja Firebase jest lazy — serwer startuje bez credentials (publiczne endpointy działają).

System uprawnień

Role-based access control (RBAC) przez middleware require-role. Cache permission checks: 5 min. Dostępne role i uprawnienia definiowane w src/lib/permissions.ts.

Struktura projektu

src/
├── index.ts                 # Entry point (Bun.serve)
├── app.ts                   # Route mounting, CORS, OpenAPI, Scalar
├── lib/
│   ├── firebase.ts          # Firebase Admin SDK (lazy, multi-project)
│   ├── cache.ts             # In-memory cache (MemoryCache<T>)
│   ├── permissions.ts       # System uprawnień (role → permissions)
│   ├── email.ts             # Resend integration
│   ├── stripe.ts            # Stripe integration
│   ├── recaptcha.ts         # reCAPTCHA verification
│   ├── prometheus.ts        # Metryki Prometheus
│   ├── notifications.ts     # Push notifications
│   └── password-reset-*.ts  # Password reset flow (token/code stores)
├── middleware/
│   ├── firebase-auth.ts     # Bearer token verification
│   ├── optional-auth.ts     # Optional authentication
│   ├── require-role.ts      # Role/type check (cache 5 min)
│   └── prometheus.ts        # Metrics middleware
├── routes/
│   ├── system/              # /health, /metrics, /readme
│   ├── tools/               # /tools/synevo-services
│   ├── dev/                 # /tools/auth/firebase (dev only)
│   └── v1/
│       ├── auth/            # /v1/auth/* (login, verify, logout, password)
│       └── codes/           # /v1/codes/* (CRUD kodów)
├── integrations/
│   └── opencv-ocr.ts        # OpenCV OCR integration
└── scripts/
    ├── seed-score2.ts       # Seed algorytmu SCORE2
    ├── seed-wcrf.ts         # Seed algorytmu WCRF
    └── set-password.ts      # Narzędzie do ustawiania haseł

Docker

docker build -t wellysa-api .
docker run -p 3000:3000 --env-file .env wellysa-api

Multi-stage build na oven/bun:1 — minimalistyczny obraz produkcyjny (frozen lockfile + production dependencies only).

Deploy (Railway)

Wymagane zmienne na Railway:

• NODE_ENV=production
• FIREBASE_ORAP_SERVICE_ACCOUNT i FIREBASE_ORAM_SERVICE_ACCOUNT
• RESEND_API_KEY, STRIPE_SECRET_KEY, RECAPTCHA_SECRET_KEY
• PORT ustawiany automatycznie przez Railway

Development Scripts

bun dev              # Hot-reload development server
bun run build        # TypeScript type-check (no emit)
bun test             # Run test suite
bun run seed:score2  # Seed SCORE2 algorithm data
bun run seed:wcrf    # Seed WCRF algorithm data

Status

Aktywny development. Core features (auth, system endpoints, codes) zaimplementowane. Products, Users, Collection Points, Algorithms — w trakcie migracji z Firebase Functions (zweryfikuj aktualny stan z zespołem).