docs: reorder & testing

pkg/model/order/order.go

@@ -2,8 +2,50 @@ package order
 
 import (
 	"encoding/json"
+
+	"github.com/google/uuid"
 )
 
+// MessageTypeUserGamesCommand is the authenticated gateway message type
+// used to send a batch of in-game commands to the engine through
+// `POST /api/v1/user/games/{game_id}/commands`. The signed payload is
+// a FlatBuffers `order.UserGamesCommand`.
+const MessageTypeUserGamesCommand = "user.games.command"
+
+// MessageTypeUserGamesOrder is the authenticated gateway message type
+// used to validate / store a batch of in-game orders through
+// `POST /api/v1/user/games/{game_id}/orders`. The signed payload is a
+// FlatBuffers `order.UserGamesOrder`.
+const MessageTypeUserGamesOrder = "user.games.order"
+
+// UserGamesCommand is the typed payload of MessageTypeUserGamesCommand.
+// `GameID` selects the running engine container; `Commands` is the
+// player command batch executed atomically by the engine. The `Actor`
+// field present in the engine's JSON shape is rebuilt by backend from
+// the runtime player mapping — clients never carry it.
+type UserGamesCommand struct {
+	// GameID identifies the running game for this batch.
+	GameID uuid.UUID `json:"game_id"`
+
+	// Commands is the player command batch.
+	Commands []DecodableCommand `json:"cmd"`
+}
+
+// UserGamesOrder is the typed payload of MessageTypeUserGamesOrder.
+// Mirrors `UserGamesCommand` plus an `UpdatedAt` field that lets the
+// engine reject stale order submissions.
+type UserGamesOrder struct {
+	// GameID identifies the running game for this batch.
+	GameID uuid.UUID `json:"game_id"`
+
+	// UpdatedAt is the client-side timestamp used for stale-order
+	// detection on the engine side.
+	UpdatedAt int `json:"updatedAt"`
+
+	// Commands is the player order batch.
+	Commands []DecodableCommand `json:"cmd"`
+}
+
 type Order struct {
 	// TODO: check with already stored order, if any, and generate an error, if newer order exists
 	UpdatedAt int                `json:"updatedAt"`

pkg/model/report/messages.go

@@ -0,0 +1,22 @@
+package report
+
+import "github.com/google/uuid"
+
+// MessageTypeUserGamesReport is the authenticated gateway message type
+// used to fetch a per-player turn report through
+// `GET /api/v1/user/games/{game_id}/reports/{turn}`. The signed payload
+// is a FlatBuffers `GameReportRequest`; the response is a FlatBuffers
+// `Report`.
+const MessageTypeUserGamesReport = "user.games.report"
+
+// GameReportRequest is the typed payload of MessageTypeUserGamesReport.
+// `GameID` selects the target game (the message_type alone is not
+// enough; this scope is per-game) and `Turn` selects the requested
+// turn number. Both fields are required.
+type GameReportRequest struct {
+	// GameID identifies the game whose report is fetched.
+	GameID uuid.UUID `json:"game_id"`
+
+	// Turn is the zero-based turn number whose report is requested.
+	Turn uint `json:"turn"`
+}

pkg/model/user/user.go

@@ -16,6 +16,19 @@ const (
 	// MessageTypeUpdateMySettings is the authenticated gateway message type used
 	// to mutate self-service settings fields.
 	MessageTypeUpdateMySettings = "user.settings.update"
+
+	// MessageTypeListMySessions is the authenticated gateway message type used
+	// to read the caller's active device sessions.
+	MessageTypeListMySessions = "user.sessions.list"
+
+	// MessageTypeRevokeMySession is the authenticated gateway message type used
+	// to revoke one of the caller's device sessions.
+	MessageTypeRevokeMySession = "user.sessions.revoke"
+
+	// MessageTypeRevokeAllMySessions is the authenticated gateway message type
+	// used to revoke every device session belonging to the caller (logout
+	// everywhere).
+	MessageTypeRevokeAllMySessions = "user.sessions.revoke_all"
 )
 
 // GetMyAccountRequest stores the authenticated self-service read request for
@@ -198,3 +211,78 @@ type ErrorResponse struct {
 	// Error stores the mirrored error envelope body.
 	Error ErrorBody `json:"error"`
 }
+
+// DeviceSession stores the transport-ready snapshot of one device session
+// served by the authenticated user-surface session endpoints.
+type DeviceSession struct {
+	// DeviceSessionID stores the durable device-session identifier.
+	DeviceSessionID string `json:"device_session_id"`
+
+	// UserID stores the authenticated user identity bound to the session.
+	UserID string `json:"user_id"`
+
+	// Status stores the lifecycle state of the session
+	// (`active` or `revoked`).
+	Status string `json:"status"`
+
+	// ClientPublicKey stores the standard base64-encoded raw 32-byte
+	// Ed25519 client public key, when populated.
+	ClientPublicKey string `json:"client_public_key,omitempty"`
+
+	// CreatedAt stores when the session was created.
+	CreatedAt time.Time `json:"created_at"`
+
+	// RevokedAt stores when the session was revoked, if revoked.
+	RevokedAt *time.Time `json:"revoked_at,omitempty"`
+
+	// LastSeenAt stores when gateway last resolved this session.
+	LastSeenAt *time.Time `json:"last_seen_at,omitempty"`
+}
+
+// ListMySessionsRequest stores the authenticated self-service "list my
+// active sessions" command. The body is intentionally empty.
+type ListMySessionsRequest struct{}
+
+// ListMySessionsResponse stores the success payload of MessageTypeListMySessions.
+type ListMySessionsResponse struct {
+	// Items stores the caller's currently active device sessions.
+	Items []DeviceSession `json:"items"`
+}
+
+// RevokeMySessionRequest stores the authenticated self-service single
+// session revocation request.
+type RevokeMySessionRequest struct {
+	// DeviceSessionID identifies the device session to revoke. The
+	// session must belong to the caller; otherwise the response carries
+	// the same error shape as a missing session so foreign session ids
+	// cannot be probed.
+	DeviceSessionID string `json:"device_session_id"`
+}
+
+// RevokeMySessionResponse stores the success payload of
+// MessageTypeRevokeMySession.
+type RevokeMySessionResponse struct {
+	// Session stores the post-revoke snapshot of the affected session.
+	Session DeviceSession `json:"session"`
+}
+
+// RevokeAllMySessionsRequest stores the authenticated self-service
+// "logout everywhere" command. The body is intentionally empty.
+type RevokeAllMySessionsRequest struct{}
+
+// DeviceSessionRevocationSummary stores the count of sessions revoked by a
+// bulk operation.
+type DeviceSessionRevocationSummary struct {
+	// UserID identifies the user whose sessions were affected.
+	UserID string `json:"user_id"`
+
+	// RevokedCount stores how many sessions transitioned to revoked.
+	RevokedCount int `json:"revoked_count"`
+}
+
+// RevokeAllMySessionsResponse stores the success payload of
+// MessageTypeRevokeAllMySessions.
+type RevokeAllMySessionsResponse struct {
+	// Summary stores the user_id and revoked_count snapshot.
+	Summary DeviceSessionRevocationSummary `json:"summary"`
+}