feat(scum): add versioned gift grants

platform/api/game_gift_handlers.go

@@ -0,0 +1,141 @@
+package api
+
+import (
+	"browser.local/platform/dto"
+	"browser.local/platform/repo"
+	"net/http"
+)
+
+// serverGameGiftCatalogs godoc
+// @Summary List or create SCUM versioned gift catalogs
+// @Description Manages bounded drafts that contain catalog references only, never raw game item commands.
+// @Tags game-gifts
+// @Produce json
+// @Router /api/v1/server-instances/{id}/game-gifts [get,post]
+func (h *coreHandlers) serverGameGiftCatalogs(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		values, err := h.core.ListGameGiftCatalogsForSession(bearerToken(r), r.PathValue("id"))
+		if err != nil {
+			writeServiceError(w, err)
+			return
+		}
+		writeJSON(w, http.StatusOK, dto.GameGiftCatalogsFromDomain(values))
+	case http.MethodPost:
+		request, err := decodeJSON[dto.GameGiftCatalogRequest](r)
+		if err != nil {
+			writeDecodeError(w, err)
+			return
+		}
+		value, err := h.core.SaveGameGiftCatalogForSession(bearerToken(r), r.PathValue("id"), request.ToDomain())
+		if err != nil {
+			writeServiceError(w, err)
+			return
+		}
+		writeJSON(w, http.StatusCreated, dto.GameGiftCatalogFromDomain(value))
+	default:
+		writeMethodNotAllowed(w, "GET, POST")
+	}
+}
+
+// serverGameGiftCatalogPublish godoc
+// @Summary Publish immutable SCUM gift revision
+// @Description Freezes a validated version-fenced gift draft.
+// @Tags game-gifts
+// @Produce json
+// @Router /api/v1/server-instances/{id}/game-gifts/{catalogId}/publish [post]
+func (h *coreHandlers) serverGameGiftCatalogPublish(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeMethodNotAllowed(w, http.MethodPost)
+		return
+	}
+	value, err := h.core.PublishGameGiftCatalogForSession(bearerToken(r), r.PathValue("catalogId"))
+	if err != nil {
+		writeServiceError(w, err)
+		return
+	}
+	if value.ServerInstanceID != r.PathValue("id") {
+		writeServiceError(w, repo.ErrNotFound)
+		return
+	}
+	writeJSON(w, http.StatusCreated, dto.GameGiftRevisionFromDomain(value))
+}
+
+// serverGameGiftCatalogRevisions godoc
+// @Summary List immutable SCUM gift revisions
+// @Tags game-gifts
+// @Produce json
+// @Router /api/v1/server-instances/{id}/game-gifts/{catalogId}/revisions [get]
+func (h *coreHandlers) serverGameGiftCatalogRevisions(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeMethodNotAllowed(w, http.MethodGet)
+		return
+	}
+	values, err := h.core.ListGameGiftRevisionsForSession(bearerToken(r), r.PathValue("catalogId"))
+	if err != nil {
+		writeServiceError(w, err)
+		return
+	}
+	for _, v := range values {
+		if v.ServerInstanceID != r.PathValue("id") {
+			writeServiceError(w, repo.ErrNotFound)
+			return
+		}
+	}
+	writeJSON(w, http.StatusOK, dto.GameGiftRevisionsFromDomain(values))
+}
+
+// serverGameGiftGrants godoc
+// @Summary List or request directed SCUM gift grants
+// @Description Creates frozen local-player grants for platform-admin approval without raw commands or item codes.
+// @Tags game-gifts
+// @Produce json
+// @Router /api/v1/server-instances/{id}/game-gift-grants [get,post]
+func (h *coreHandlers) serverGameGiftGrants(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		values, err := h.core.ListGameGiftGrantsForSession(bearerToken(r), r.PathValue("id"))
+		if err != nil {
+			writeServiceError(w, err)
+			return
+		}
+		writeJSON(w, http.StatusOK, dto.GameGiftGrantsFromDomain(values))
+	case http.MethodPost:
+		request, err := decodeJSON[dto.GameGiftGrantRequest](r)
+		if err != nil {
+			writeDecodeError(w, err)
+			return
+		}
+		value, err := h.core.RequestGameGiftGrantForSession(bearerToken(r), r.PathValue("id"), request.ToDomain())
+		if err != nil {
+			writeServiceError(w, err)
+			return
+		}
+		writeJSON(w, http.StatusAccepted, dto.GameGiftGrantFromDomain(value))
+	default:
+		writeMethodNotAllowed(w, "GET, POST")
+	}
+}
+
+// serverGameGiftGrantApprove godoc
+// @Summary Approve a frozen directed SCUM gift grant
+// @Description Requires a platform administrator and dispatches only the declared typed reward command.
+// @Tags game-gifts
+// @Produce json
+// @Router /api/v1/server-instances/{id}/game-gift-grants/{grantId}/approve [post]
+func (h *coreHandlers) serverGameGiftGrantApprove(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeMethodNotAllowed(w, http.MethodPost)
+		return
+	}
+	value, err := h.core.ApproveGameGiftGrantForSession(bearerToken(r), r.PathValue("grantId"))
+	if err != nil {
+		writeServiceError(w, err)
+		return
+	}
+	if value.ServerInstanceID != r.PathValue("id") {
+		writeServiceError(w, repo.ErrNotFound)
+		return
+	}
+	writeJSON(w, http.StatusAccepted, dto.GameGiftGrantFromDomain(value))
+}

platform/api/resource_handlers.go

@@ -98,6 +98,11 @@ func (h *coreHandlers) register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/server-instances/{id}/game-players/{playerId}/state", h.serverGamePlayerState)
 	mux.HandleFunc("/api/v1/server-instances/{id}/game-players/{playerId}/state-patches", h.serverGamePlayerStatePatches)
 	mux.HandleFunc("/api/v1/server-instances/{id}/game-players/{playerId}/state-patches/{patchId}/approve", h.serverGamePlayerStatePatchApprove)
+	mux.HandleFunc("/api/v1/server-instances/{id}/game-gifts", h.serverGameGiftCatalogs)
+	mux.HandleFunc("/api/v1/server-instances/{id}/game-gifts/{catalogId}/publish", h.serverGameGiftCatalogPublish)
+	mux.HandleFunc("/api/v1/server-instances/{id}/game-gifts/{catalogId}/revisions", h.serverGameGiftCatalogRevisions)
+	mux.HandleFunc("/api/v1/server-instances/{id}/game-gift-grants", h.serverGameGiftGrants)
+	mux.HandleFunc("/api/v1/server-instances/{id}/game-gift-grants/{grantId}/approve", h.serverGameGiftGrantApprove)
 	mux.HandleFunc("/api/v1/server-instances/{id}/dependencies/check", h.serverDependenciesCheck)
 	mux.HandleFunc("/api/v1/server-instances/{id}/dependencies/install", h.serverDependenciesInstall)
 	mux.HandleFunc("/api/v1/server-instances/{id}/dependencies", h.serverDependencies)