feat(api): add POST /api/events handler

Discriminated-union JSON over three event types: play_started,
play_ended, play_skipped. Auth via existing RequireUser. play_started
returns play_event_id + session_id; the other two return { ok: true }.
Validates ownership: play_ended/play_skipped on another user's row
returns 403. Mount signature now takes EventsConfig and constructs
the playevents.Writer; server.New propagates it through.

internal/api/events.go

@@ -0,0 +1,168 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/auth"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+type eventRequest struct {
+	Type             string  `json:"type"`
+	TrackID          string  `json:"track_id"`
+	PlayEventID      string  `json:"play_event_id"`
+	DurationPlayedMs *int32  `json:"duration_played_ms"`
+	PositionMs       *int32  `json:"position_ms"`
+	At               *string `json:"at"`
+	ClientID         *string `json:"client_id"`
+}
+
+type playStartedResponse struct {
+	PlayEventID string `json:"play_event_id"`
+	SessionID   string `json:"session_id"`
+}
+
+type okResponse struct {
+	OK bool `json:"ok"`
+}
+
+func (h *handlers) handleEvents(w http.ResponseWriter, r *http.Request) {
+	user, ok := auth.UserFromContext(r.Context())
+	if !ok {
+		writeErr(w, http.StatusUnauthorized, "unauthorized", "authentication required")
+		return
+	}
+	var req eventRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeErr(w, http.StatusBadRequest, "bad_request", "invalid JSON body")
+		return
+	}
+	at := time.Now().UTC()
+	if req.At != nil && *req.At != "" {
+		parsed, err := time.Parse(time.RFC3339, *req.At)
+		if err != nil {
+			writeErr(w, http.StatusBadRequest, "bad_request", "invalid `at` timestamp")
+			return
+		}
+		at = parsed
+	}
+	clientID := ""
+	if req.ClientID != nil {
+		clientID = *req.ClientID
+	}
+	switch req.Type {
+	case "play_started":
+		h.handleEventPlayStarted(w, r, user, req, at, clientID)
+	case "play_ended":
+		h.handleEventPlayEnded(w, r, user, req, at)
+	case "play_skipped":
+		h.handleEventPlaySkipped(w, r, user, req, at)
+	default:
+		writeErr(w, http.StatusBadRequest, "bad_request", "unknown event type")
+	}
+}
+
+func (h *handlers) handleEventPlayStarted(
+	w http.ResponseWriter, r *http.Request,
+	user dbq.User, req eventRequest, at time.Time, clientID string,
+) {
+	trackID, ok := parseUUID(req.TrackID)
+	if !ok {
+		writeErr(w, http.StatusBadRequest, "bad_request", "invalid track_id")
+		return
+	}
+	if _, err := dbq.New(h.pool).GetTrackByID(r.Context(), trackID); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			writeErr(w, http.StatusNotFound, "not_found", "track not found")
+			return
+		}
+		h.logger.Error("api: events: lookup track", "err", err)
+		writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
+		return
+	}
+	res, err := h.events.RecordPlayStarted(r.Context(), user.ID, trackID, clientID, at)
+	if err != nil {
+		h.logger.Error("api: events: play_started", "err", err)
+		writeErr(w, http.StatusInternalServerError, "server_error", "record failed")
+		return
+	}
+	writeJSON(w, http.StatusOK, playStartedResponse{
+		PlayEventID: uuidToString(res.PlayEventID),
+		SessionID:   uuidToString(res.SessionID),
+	})
+}
+
+func (h *handlers) handleEventPlayEnded(
+	w http.ResponseWriter, r *http.Request,
+	user dbq.User, req eventRequest, at time.Time,
+) {
+	playEventID, ok := parseUUID(req.PlayEventID)
+	if !ok {
+		writeErr(w, http.StatusBadRequest, "bad_request", "invalid play_event_id")
+		return
+	}
+	if req.DurationPlayedMs == nil || *req.DurationPlayedMs < 0 {
+		writeErr(w, http.StatusBadRequest, "bad_request", "duration_played_ms required and must be >= 0")
+		return
+	}
+	ev, err := dbq.New(h.pool).GetPlayEventByID(r.Context(), playEventID)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			writeErr(w, http.StatusNotFound, "not_found", "play_event not found")
+			return
+		}
+		h.logger.Error("api: events: lookup play_event", "err", err)
+		writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
+		return
+	}
+	if ev.UserID != user.ID {
+		writeErr(w, http.StatusForbidden, "forbidden", "play_event belongs to a different user")
+		return
+	}
+	if err := h.events.RecordPlayEnded(r.Context(), playEventID, *req.DurationPlayedMs, at); err != nil {
+		h.logger.Error("api: events: play_ended", "err", err)
+		writeErr(w, http.StatusInternalServerError, "server_error", "record failed")
+		return
+	}
+	writeJSON(w, http.StatusOK, okResponse{OK: true})
+}
+
+func (h *handlers) handleEventPlaySkipped(
+	w http.ResponseWriter, r *http.Request,
+	user dbq.User, req eventRequest, at time.Time,
+) {
+	playEventID, ok := parseUUID(req.PlayEventID)
+	if !ok {
+		writeErr(w, http.StatusBadRequest, "bad_request", "invalid play_event_id")
+		return
+	}
+	if req.PositionMs == nil || *req.PositionMs < 0 {
+		writeErr(w, http.StatusBadRequest, "bad_request", "position_ms required and must be >= 0")
+		return
+	}
+	ev, err := dbq.New(h.pool).GetPlayEventByID(r.Context(), playEventID)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			writeErr(w, http.StatusNotFound, "not_found", "play_event not found")
+			return
+		}
+		h.logger.Error("api: events: lookup play_event", "err", err)
+		writeErr(w, http.StatusInternalServerError, "server_error", "lookup failed")
+		return
+	}
+	if ev.UserID != user.ID {
+		writeErr(w, http.StatusForbidden, "forbidden", "play_event belongs to a different user")
+		return
+	}
+	if err := h.events.RecordPlaySkipped(r.Context(), playEventID, *req.PositionMs, at); err != nil {
+		h.logger.Error("api: events: play_skipped", "err", err)
+		writeErr(w, http.StatusInternalServerError, "server_error", "record failed")
+		return
+	}
+	writeJSON(w, http.StatusOK, okResponse{OK: true})
+}