GrzybcioRynekWeb

HTTP REST / SSE bridge between GrzybcioRynek and a public marketplace website.

This is not a second market plugin. GrzybcioRynekWeb does not store listings, does not touch Vault, and does not read listings.yml. It exposes live market data from GrzybcioRynek through a read-only HTTP API.

Website (Next.js)  →  GrzybcioRynekWeb  →  GrzybcioRynek MarketAPI

---

Features

• REST API — listings, categories, stats, transaction history, player profiles, price history
• Server-Sent Events (SSE) — live updates when listings are created, sold, removed, or expired
• API key authentication — read-only permissions; write endpoints return 403 WRITE_NOT_ENABLED
• CORS — explicit origin allowlist (no * in production)
• Rate limiting — per IP and per API key
• Response cache — configurable TTL for listings, stats, players, and history
• OpenAPI 3 — interactive docs at /api/docs and /api/openapi.json
• Admin commands — status, reload, cache management, key names (secrets never printed)

---

Requirements

Requirement	Version
Server	Paper 26.2
Java	25
GrzybcioRynek	1.0.3+ (required dependency)
Vault + economy	Required by GrzybcioRynek

GrzybcioRynekWeb checks the installed GrzybcioRynek version and API contract (1). If GrzybcioRynek is missing, disabled, or incompatible, the bridge will not start.

---

Installation

1. Install and configure GrzybcioRynek (Vault + economy must work).
2. Drop GrzybcioRynekWeb-1.0.0.jar into your plugins/ folder.
3. Start the server once to generate plugins/GrzybcioRynekWeb/config.yml.
4. Edit the config (see below) — change CHANGE_ME API keys before exposing the port.
5. Restart the server (or run /grzybciorynekweb reload after YAML-only changes).
6. Verify:
   • In-game: /grzybciorynekweb status
   • HTTP: GET http://your-server:8765/api/v1/health

---

Configuration

Default port: 8765 (api.host: 0.0.0.0).

API key (recommended for production)

api:
  authentication:
    enabled: true
    keys:
      - name: "website"
        key: "your-secret-key-here"
        permissions:
          - "listings.read"
          - "categories.read"
          - "stats.read"
          - "history.read"
          - "players.read"

Send the key as X-API-Key: … or Authorization: Bearer ….
For SSE (EventSource), use ?api_key=… on /api/v1/events only.

CORS (browser → plugin directly)

If your website calls the plugin from the browser without a server-side proxy, add your site origin:

api:
  cors:
    enabled: true
    allowed-origins:
      - "https://your-market.example.com"
      - "http://localhost:3000"

The bundled Next.js marketplace uses a same-origin proxy instead, so CORS on the plugin is optional when you deploy that way.

Security checklist

• Replace every CHANGE_ME key before going public
• Do not expose port 8765 to the internet without auth, firewall, or a reverse proxy
• Keep authentication.enabled: true on production servers
• Never put API keys in client-side NEXT_PUBLIC_* env vars

---

Commands

Command	Permission	Description
/grzybciorynekweb status	grybciorynekweb.admin	Bridge, REST, SSE, cache, and metrics
/grzybciorynekweb reload	grybciorynekweb.admin	Reload config and restart HTTP if bind changed
/grzybciorynekweb key	grybciorynekweb.admin	List configured key names (not secrets)
/grzybciorynekweb cache clear	grybciorynekweb.admin	Invalidate API cache

Alias: /grynekweb

---

API overview

Base path: /api/v1

Endpoint	Description
GET /health	Bridge status (no key required)
GET /listings	Paginated active listings
GET /listings/{id}	Single listing
GET /categories	Market categories
GET /stats	Market statistics
GET /history	Public transaction history
GET /price-history/{item}	Price chart data
GET /players/{name|uuid}	Seller profile
GET /players/{id}/listings	Player listings
GET /sellers	Unique seller names
GET /events	SSE stream
GET /api/docs	HTML documentation

Full reference: see docs/API.md in the source repository.

---

Links

• GrzybcioRynek on Modrinth — required market plugin (1.0.3+)
• Marketplace website — download and self-host (Next.js)
• Documentation wiki — web integration, API, hosting

---

Companion website

Download and self-host the public marketplace frontend from GrzybcioRynekWeb-strona (Next.js). It connects through a server-side proxy so your API key stays on the host (VPS, Docker, Vercel, etc.).

Typical env vars on the website host:

MARKET_API_URL=https://your-public-api-url:8765
MARKET_API_KEY=your-read-key
NEXT_PUBLIC_MARKET_SSE=false

Expose GrzybcioRynekWeb with a Cloudflare Tunnel, reverse proxy, or public IP — Vercel cannot reach 127.0.0.1 on your game server.

---

What this plugin does not do

• Create, edit, or delete listings over HTTP (v1 is read-only)
• Replace GrzybcioRynek or duplicate its market logic
• Run without GrzybcioRynek installed and enabled

---

License

Apache License 2.0

GrzybcioRynek and GrzybcioRynekWeb are not affiliated with Mojang Studios.

---

---

GrzybcioRynekWeb (PL)

Most HTTP REST / SSE między GrzybcioRynek a publiczną stroną rynku.

To nie jest drugi plugin rynkowy. GrzybcioRynekWeb nie trzyma ofert, nie rusza Vault i nie czyta listings.yml. Udostępnia na żywo dane z GrzybcioRynek przez tylko do odczytu HTTP API.

Strona (Next.js)  →  GrzybcioRynekWeb  →  GrzybcioRynek MarketAPI

---

Funkcje

• REST API — oferty, kategorie, statystyki, historia transakcji, profile graczy, historia cen
• Server-Sent Events (SSE) — na żywo: nowa oferta, sprzedaż, usunięcie, wygaśnięcie
• Klucze API — uprawnienia tylko do odczytu; zapis przez HTTP zwraca 403 WRITE_NOT_ENABLED
• CORS — jawna lista originów (bez * na produkcji)
• Rate limiting — per IP i per klucz API
• Cache odpowiedzi — konfigurowalny TTL
• OpenAPI 3 — dokumentacja pod /api/docs i /api/openapi.json
• Komendy admina — status, reload, cache, nazwy kluczy (sekrety nigdy nie są wyświetlane)

---

Wymagania

Wymaganie	Wersja
Serwer	Paper 26.2
Java	25
GrzybcioRynek	1.0.3+ (wymagana zależność)
Vault + ekonomia	Wymagane przez GrzybcioRynek

Most sprawdza wersję GrzybcioRynek i kontrakt API (1). Jeśli GrzybcioRynek nie ma, jest wyłączony albo niekompatybilny — most się nie uruchomi.

---

Instalacja

1. Zainstaluj i skonfiguruj GrzybcioRynek (Vault + ekonomia muszą działać).
2. Wgraj GrzybcioRynekWeb-1.0.0.jar do plugins/.
3. Uruchom serwer raz — powstanie plugins/GrzybcioRynekWeb/config.yml.
4. Edytuj config (poniżej) — zmień klucz CHANGE_ME zanim wystawisz port na świat.
5. Zrestartuj serwer (albo /grzybciorynekweb reload po samych zmianach w YAML).
6. Sprawdź:
   • W grze: /grzybciorynekweb status
   • HTTP: GET http://twoj-serwer:8765/api/v1/health

---

Konfiguracja

Domyślny port: 8765 (api.host: 0.0.0.0).

Klucz API (zalecane na produkcji)

api:
  authentication:
    enabled: true
    keys:
      - name: "website"
        key: "twoj-tajny-klucz"
        permissions:
          - "listings.read"
          - "categories.read"
          - "stats.read"
          - "history.read"
          - "players.read"

Wyślij klucz jako X-API-Key: … albo Authorization: Bearer ….
Dla SSE (EventSource) użyj ?api_key=… tylko na /api/v1/events.

CORS (przeglądarka → plugin bezpośrednio)

Jeśli strona woła plugin z przeglądarki bez proxy po stronie serwera, dopisz origin:

api:
  cors:
    enabled: true
    allowed-origins:
      - "https://twoj-rynek.example.com"
      - "http://localhost:3000"

Dołączona strona Next.js używa proxy na tej samej domenie — wtedy CORS w pluginie nie jest konieczny.

Checklist bezpieczeństwa

• Zamień każdy klucz CHANGE_ME przed publikacją
• Nie wystawiaj portu 8765 na internet bez auth, firewalla albo reverse proxy
• Na produkcji trzymaj authentication.enabled: true
• Nie wkładaj kluczy API do zmiennych NEXT_PUBLIC_* po stronie strony

---

Komendy

Komenda	Uprawnienie	Opis
/grzybciorynekweb status	grybciorynekweb.admin	Most, REST, SSE, cache, metryki
/grzybciorynekweb reload	grybciorynekweb.admin	Przeładuj config; restart HTTP przy zmianie bind
/grzybciorynekweb key	grybciorynekweb.admin	Nazwy kluczy (bez sekretów)
/grzybciorynekweb cache clear	grybciorynekweb.admin	Wyczyść cache API

Alias: /grynekweb

---

API — skrót

Prefiks: /api/v1

Endpoint	Opis
GET /health	Status mostu (bez klucza)
GET /listings	Paginowane oferty
GET /listings/{id}	Jedna oferta
GET /categories	Kategorie
GET /stats	Statystyki rynku
GET /history	Publiczna historia TX
GET /price-history/{item}	Punkty wykresu ceny
GET /players/{nick|uuid}	Profil sprzedawcy
GET /players/{id}/listings	Oferty gracza
GET /sellers	Unikalne nicki
GET /events	Strumień SSE
GET /api/docs	Dokumentacja HTML

Pełna referencja: docs/API.md w repozytorium.

---

Linki

• GrzybcioRynek na Modrinth — wymagany plugin rynku (1.0.3+)
• Strona rynku — pobieranie i samohostowanie (Next.js)
• Wiki dokumentacji — integracja WWW, API, hosting

---

Strona towarzysząca

Publiczną stronę rynku pobierzesz i samodzielnie hostujesz z GrzybcioRynekWeb-strona (Next.js). Łączy się przez proxy po stronie hosta — klucz API zostaje na serwerze (VPS, Docker, Vercel itd.).

Typowe zmienne na hoście strony:

MARKET_API_URL=https://twoj-publiczny-adres-api:8765
MARKET_API_KEY=klucz-odczytu
NEXT_PUBLIC_MARKET_SSE=false

Wystaw GrzybcioRynekWeb przez Cloudflare Tunnel, reverse proxy albo publiczne IP — Vercel nie dosięgnie 127.0.0.1 na Twoim serwerze gry.

---

Czego plugin nie robi

• Nie tworzy, edytuje ani nie usuwa ofert przez HTTP (v1 = tylko odczyt)
• Nie zastępuje GrzybcioRynek ani nie duplikuje logiki rynku
• Nie działa bez zainstalowanego i włączonego GrzybcioRynek

---

Licencja

Apache License 2.0

GrzybcioRynek i GrzybcioRynekWeb nie są powiązane z Mojang Studios.