Web-/Commerce-API (JuByteWeb)

Vollständige Referenz der JuByteWeb-Plattform — dem zentralen Portal für Lizenzen, Store, Bezahlung, Releases/Downloads, Organisationen und das Lizenz-Backend des Nexus Core. JuByteWeb ist eine Next.js-16-App (App Router); alle Endpunkte liegen unter app/api/**/route.ts.

Diese Seite katalogisiert jeden Endpunkt nach Domäne, beschreibt das Datenmodell und zeigt Entwickler-Beispiele. Verwandt: Lizenz-API & Entitlement-Vertrag und Module lizenzieren & verkaufen.

Auth-Klassen in den Tabellen: Public (kein Login), Session (eingeloggter User via Cookie), Admin (Session + Permission-Key, z. B. admin.licenses.view), Token (Shared-Secret/Signatur, für Core/CI/Webhooks).

1. Authentifizierung & Konto

Login, Registrierung, Session

2FA (TOTP)

Passkeys (WebAuthn)

Sessions & Discord

Beispiel: Login mit fetch

const res = await fetch('/api/auth/login', {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password }),
});
const data = await res.json();
if (data.requires2fa) {
  // → /api/auth/2fa/verify mit { challengeToken: data.challengeToken, code }
}

2. Store & Katalog

Preis-Tiers & Bundles

Beispiel: öffentlicher Katalog

curl https://test.jubyte.com/api/store/products | jq '.products[] | {key, name, tiers: .priceTiers}'

3. Commerce / Checkout & Bezahlung

Checkout-Request (gekürzt):

{
  "items": [ { "product": "bansystem", "tier": "pro" } ],
  "currency": "EUR",
  "billingName": "Max Mustermann",
  "billingCountry": "DE",
  "withdrawalWaived": true,
  "agreeTerms": true,
  "agreePrivacy": true
}

Antwort: { "orderId": "…", "approvalUrl": "https://www.paypal.com/checkoutnow?token=…" }. Pro Item entsteht eine Order; alle teilen sich die paypalOrderId.

Ablauf (PayPal): checkout (Order erstellen) → Kunde genehmigt → capture (serverseitig) → Webhook (asynchrone Bestätigung + Buchung im Ledger).

4. Orders & Rechnungen

5. Lizenzen

Portal (eigene/Org-Lizenzen)

Admin

Lizenz-Server-API v1 (für den Core)

Der Entitlement-Vertrag (RS256-JWS, Claims plan/status/expires/limits/features/ modules/grace_hours) ist in der Lizenz-API vollständig beschrieben. Der Core holt und aktiviert ihn automatisch.

Beispiel: Verify (Core → Web)

curl -X POST https://test.jubyte.com/api/v1/license/verify \
  -H "Content-Type: application/json" \
  -d '{"key":"NX-XXXX-XXXX","serverId":"srv-abc","version":"1.2.0","channel":"RELEASE"}'
# → { "allowed": true, "status": "ACTIVE", "license": {…}, "latestStableVersion": "1.2.0" }

6. Releases & Downloads

Channels: RELEASE (alle), BETA/SNAPSHOT (nur mit Gruppen-Grant via ProductChannelGrant). Release-Status: DRAFT/PUBLISHED/DEPRECATED.

7. Organisationen & Teams

8. Berechtigungen, Gruppen & Discord-Mapping

Permission-Key-Muster: admin.{resource}.{action} (z. B. admin.licenses.manage). Store-Sichtbarkeit über store.product.<key>.

9. Nexus-Modul-Registry & Entitlements

Dieses datengetriebene Registry ist das Herzstück der Lizenzintegration: Das ACP selbst ist als kind=CORE modelliert, jedes Plugin als kind=MODULE; beliebig viele Module lassen sich hinzufügen. Die aufgelöste Modul-Liste wird als modules[]-Claim ins signierte Entitlement geschrieben. Siehe Module lizenzieren & verkaufen.

10. Buchhaltung, Sales, Metriken & Admin

Support, Notifications, DSGVO

11. Datenmodell (Prisma)

Zentrale Entitäten und Relationen (Auszug):

Identität: User (email unique, role, emailVerifiedAt) ─ Session, UserTwoFactor, UserDiscord, Passkey, EmailVerificationToken, PasswordResetToken, AuditLog.

Lizenzierung: License (key unique, product?/productId?, plan, status ∈ ACTIVE/SUSPENDED/EXPIRED/REVOKED, expiresAt?, maxServers?) ─ LicenseBinding (serverId, lastSeenAt), LicenseEvent, LicenseOwnership (USER/ORG), LicenseModuleGrant → NexusModule (moduleId unique, kind CORE/MODULE, premium).

Katalog: Product (key/slug unique, category, productType, status) ─ ProductPriceTier (priceEur, durationDays?, featuresJson, maxServers?), ProductBundleItem, ProductGroupGrant, ProductChannelGrant, Release (version, channel, status, artifactKey, sha256), ProductDefault, DownloadLog.

Commerce: Order (status ∈ CREATED/PENDING/ACTIVE/FAILED/CANCELLED/ REFUNDED, paypalOrderId?) ─ Payment (provider PAYPAL, status, amount), Invoice (invoiceNumber unique), WebhookEvent (eventId unique).

Buchhaltung: LedgerAccount (code, type ASSET/LIABILITY/REVENUE/ EXPENSE) ─ LedgerTransaction (referenceType ORDER/PAYMENT/REFUND/MANUAL) ─ LedgerEntry (debit/credit, doppelte Buchung: Soll = Haben). Sale (saleType PERCENTAGE/FIXED_AMOUNT).

Organisationen: Organization (slug unique) ─ OrgMember (role OWNER/ADMIN/SUPPORT/BILLING), OrgGroup, OrgGroupMember, OrgGroupPermission, OrgInvite (7-Tage-TTL), OrgApiKey.

Rechte: Group (name/slug unique, weight, isSystem) ─ Permission (key unique), GroupPermission, UserGroup, GroupDiscordRole. DiscordRoleMapping (type PLAN/PRODUCT/ORG_ROLE), DiscordSyncJob.

Sonstiges: OutboxEvent (transaktionaler Outbox-Pattern), UserNotification, SupportTicket/Reply, AccountDeletionRequest, SecurityFlag, SiteSetting, StoreItem/StoreItemPermission.

12. Konventionen

Beispiel: Admin-Aufruf mit Permission

# Session-Cookie + Permission admin.licenses.view erforderlich
curl https://test.jubyte.com/api/admin/[email protected] \
  -H "Cookie: $SESSION_COOKIE" | jq '.licenses[] | {key, status, plan}'

Siehe auch

• Lizenz-API & Entitlement-Vertrag – RS256-JWS-Details
• Module lizenzieren & verkaufen
• Core-API – Gegenstück im Nexus Core