Stage 9: Telegram integration (connector side-service, Mini App, out-of-app push)

New platform/telegram connector (own container, bot token only there):
- go-telegram/bot long-poll loop: /start deep-links + Mini App launch button.
- gRPC API pkg/proto/telegram/v1 (Telegram service): ValidateInitData, Notify
  (renders a localized message + deep-link button), SendToUser/SendToGameChannel
  (admin, wired in Stage 10). Generic methods are platform-agnostic (external_id).
- Bot API base override for Telegram's test environment; Dockerfile + compose
  (VPN sidecar, no public ingress); README.

Gateway:
- initData validation relocated from the gateway into the connector; the gateway
  calls ValidateInitData over gRPC (GATEWAY_CONNECTOR_ADDR), drops the bot token,
  and deletes internal/auth.
- Out-of-app push: runPushPump routes events whose recipient has no live in-app
  stream to connector.Notify, gated by /internal/push-target + the in-app-only
  flag (race-free de-dup); HasSubscribers added to the push hub.

Backend:
- Migration 00007 accounts.notifications_in_app_only (default true) + jetgen.
- ProvisionTelegram seeds a new account's language/display name from the launch
  fields; IdentityExternalID reverse lookup; /internal/push-target handler.

UI:
- Telegram Mini App launch: detect initData, apply themeParams, authTelegram,
  route the deep-link start_param (g/i/f); /telegram/ guard redirects outside
  Telegram. Vite relative base + telegram-web-app.js. In-app-only profile toggle;
  share-to-Telegram link for a friend code. Vitest + Playwright coverage.

Wire/docs/CI: fbs Profile/UpdateProfileRequest gain notifications_in_app_only
(Go + TS); go.work uses ./platform/telegram; go-unit.yaml covers it; PLAN,
ARCHITECTURE, FUNCTIONAL (+ru), UI_DESIGN, READMEs updated.

backend/internal/server/dto.go

@@ -35,16 +35,17 @@ type resolveResponse struct {
 // profileResponse is the authenticated account's own profile. AwayStart and AwayEnd
 // are the daily away window's "HH:MM" local-time bounds (in TimeZone).
 type profileResponse struct {
-	UserID              string `json:"user_id"`
-	DisplayName         string `json:"display_name"`
-	PreferredLanguage   string `json:"preferred_language"`
-	TimeZone            string `json:"time_zone"`
-	AwayStart           string `json:"away_start"`
-	AwayEnd             string `json:"away_end"`
-	HintBalance         int    `json:"hint_balance"`
-	BlockChat           bool   `json:"block_chat"`
-	BlockFriendRequests bool   `json:"block_friend_requests"`
-	IsGuest             bool   `json:"is_guest"`
+	UserID                 string `json:"user_id"`
+	DisplayName            string `json:"display_name"`
+	PreferredLanguage      string `json:"preferred_language"`
+	TimeZone               string `json:"time_zone"`
+	AwayStart              string `json:"away_start"`
+	AwayEnd                string `json:"away_end"`
+	HintBalance            int    `json:"hint_balance"`
+	BlockChat              bool   `json:"block_chat"`
+	BlockFriendRequests    bool   `json:"block_friend_requests"`
+	IsGuest                bool   `json:"is_guest"`
+	NotificationsInAppOnly bool   `json:"notifications_in_app_only"`
 }
 
 // tileDTO is one placed (or to-place) tile.
@@ -148,16 +149,17 @@ func sessionResponseFor(token string, acc account.Account) sessionResponse {
 // profileResponseFor projects an account into its profile DTO.
 func profileResponseFor(acc account.Account) profileResponse {
 	return profileResponse{
-		UserID:              acc.ID.String(),
-		DisplayName:         acc.DisplayName,
-		PreferredLanguage:   acc.PreferredLanguage,
-		TimeZone:            acc.TimeZone,
-		AwayStart:           acc.AwayStart.Format(awayTimeLayout),
-		AwayEnd:             acc.AwayEnd.Format(awayTimeLayout),
-		HintBalance:         acc.HintBalance,
-		BlockChat:           acc.BlockChat,
-		BlockFriendRequests: acc.BlockFriendRequests,
-		IsGuest:             acc.IsGuest,
+		UserID:                 acc.ID.String(),
+		DisplayName:            acc.DisplayName,
+		PreferredLanguage:      acc.PreferredLanguage,
+		TimeZone:               acc.TimeZone,
+		AwayStart:              acc.AwayStart.Format(awayTimeLayout),
+		AwayEnd:                acc.AwayEnd.Format(awayTimeLayout),
+		HintBalance:            acc.HintBalance,
+		BlockChat:              acc.BlockChat,
+		BlockFriendRequests:    acc.BlockFriendRequests,
+		IsGuest:                acc.IsGuest,
+		NotificationsInAppOnly: acc.NotificationsInAppOnly,
 	}
 }
 

backend/internal/server/handlers.go

@@ -31,6 +31,10 @@ func (s *Server) registerRoutes() {
 		in.POST("/sessions/email/login", s.handleEmailLogin)
 		in.POST("/sessions/resolve", s.handleResolveSession)
 		in.POST("/sessions/revoke", s.handleRevokeSession)
+		// Out-of-app push routing for the platform side-service (Stage 9): the
+		// gateway resolves a recipient's Telegram chat + language + in-app-only flag
+		// before delivering an out-of-app notification.
+		in.POST("/push-target", s.handlePushTarget)
 	}
 	u := s.user
 	if s.accounts != nil {

backend/internal/server/handlers_account.go

@@ -18,13 +18,14 @@ import (
 // updateProfileRequest is the full editable profile. away_start/away_end are
 // "HH:MM" local-time bounds of the daily away window.
 type updateProfileRequest struct {
-	DisplayName         string `json:"display_name"`
-	PreferredLanguage   string `json:"preferred_language"`
-	TimeZone            string `json:"time_zone"`
-	AwayStart           string `json:"away_start"`
-	AwayEnd             string `json:"away_end"`
-	BlockChat           bool   `json:"block_chat"`
-	BlockFriendRequests bool   `json:"block_friend_requests"`
+	DisplayName            string `json:"display_name"`
+	PreferredLanguage      string `json:"preferred_language"`
+	TimeZone               string `json:"time_zone"`
+	AwayStart              string `json:"away_start"`
+	AwayEnd                string `json:"away_end"`
+	BlockChat              bool   `json:"block_chat"`
+	BlockFriendRequests    bool   `json:"block_friend_requests"`
+	NotificationsInAppOnly bool   `json:"notifications_in_app_only"`
 }
 
 // statsDTO is a durable account's lifetime statistics (the derived games-played and
@@ -80,13 +81,14 @@ func (s *Server) handleUpdateProfile(c *gin.Context) {
 		return
 	}
 	acc, err := s.accounts.UpdateProfile(c.Request.Context(), uid, account.ProfileUpdate{
-		DisplayName:         req.DisplayName,
-		PreferredLanguage:   req.PreferredLanguage,
-		TimeZone:            req.TimeZone,
-		AwayStart:           awayStart,
-		AwayEnd:             awayEnd,
-		BlockChat:           req.BlockChat,
-		BlockFriendRequests: req.BlockFriendRequests,
+		DisplayName:            req.DisplayName,
+		PreferredLanguage:      req.PreferredLanguage,
+		TimeZone:               req.TimeZone,
+		AwayStart:              awayStart,
+		AwayEnd:                awayEnd,
+		BlockChat:              req.BlockChat,
+		BlockFriendRequests:    req.BlockFriendRequests,
+		NotificationsInAppOnly: req.NotificationsInAppOnly,
 	})
 	if err != nil {
 		s.abortErr(c, err)

backend/internal/server/handlers_auth.go

@@ -1,9 +1,11 @@
 package server
 
 import (
+	"errors"
 	"net/http"
 
 	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
 
 	"scrabble/backend/internal/account"
 )
@@ -14,21 +16,26 @@ import (
 // account and mint the opaque session. The backend trusts the gateway on this
 // segment (docs/ARCHITECTURE.md §12).
 
-// telegramAuthRequest carries the platform user id the gateway extracted from a
-// validated initData payload.
+// telegramAuthRequest carries the identity the connector extracted from a
+// validated initData payload. Username, FirstName and LanguageCode seed a
+// brand-new account's display name and language (first contact only).
 type telegramAuthRequest struct {
-	ExternalID string `json:"external_id"`
+	ExternalID   string `json:"external_id"`
+	Username     string `json:"username"`
+	FirstName    string `json:"first_name"`
+	LanguageCode string `json:"language_code"`
 }
 
 // handleTelegramAuth provisions (or finds) the account bound to a Telegram
-// identity and mints a session for it.
+// identity and mints a session for it, seeding a new account's display name and
+// language from the supplied Telegram fields.
 func (s *Server) handleTelegramAuth(c *gin.Context) {
 	var req telegramAuthRequest
 	if err := c.ShouldBindJSON(&req); err != nil || req.ExternalID == "" {
 		abortBadRequest(c, "external_id is required")
 		return
 	}
-	acc, err := s.accounts.ProvisionByIdentity(c.Request.Context(), account.KindTelegram, req.ExternalID)
+	acc, err := s.accounts.ProvisionTelegram(c.Request.Context(), req.ExternalID, req.LanguageCode, req.Username, req.FirstName)
 	if err != nil {
 		s.abortErr(c, err)
 		return
@@ -36,6 +43,53 @@ func (s *Server) handleTelegramAuth(c *gin.Context) {
 	s.mintSession(c, acc)
 }
 
+// pushTargetRequest asks for a user's out-of-app push routing data by account id.
+type pushTargetRequest struct {
+	UserID string `json:"user_id"`
+}
+
+// pushTargetResponse carries what the gateway needs to route an out-of-app push:
+// the recipient's Telegram external_id (empty when they have no Telegram
+// identity, e.g. a guest or email-only account), the preferred language for the
+// message template, and whether they confined notifications to the in-app stream.
+type pushTargetResponse struct {
+	ExternalID             string `json:"external_id"`
+	Language               string `json:"language"`
+	NotificationsInAppOnly bool   `json:"notifications_in_app_only"`
+}
+
+// handlePushTarget resolves a user id to the data the gateway needs to deliver an
+// out-of-app Telegram notification — the gateway-only internal counterpart of the
+// in-app push stream. A user with no Telegram identity yields an empty external_id,
+// which the gateway treats as "no out-of-app channel".
+func (s *Server) handlePushTarget(c *gin.Context) {
+	var req pushTargetRequest
+	if err := c.ShouldBindJSON(&req); err != nil || req.UserID == "" {
+		abortBadRequest(c, "user_id is required")
+		return
+	}
+	uid, err := uuid.Parse(req.UserID)
+	if err != nil {
+		abortBadRequest(c, "user_id must be a uuid")
+		return
+	}
+	acc, err := s.accounts.GetByID(c.Request.Context(), uid)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	ext, err := s.accounts.IdentityExternalID(c.Request.Context(), uid, account.KindTelegram)
+	if err != nil && !errors.Is(err, account.ErrNotFound) {
+		s.abortErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, pushTargetResponse{
+		ExternalID:             ext,
+		Language:               acc.PreferredLanguage,
+		NotificationsInAppOnly: acc.NotificationsInAppOnly,
+	})
+}
+
 // handleGuestAuth provisions a fresh ephemeral guest account and mints a session.
 func (s *Server) handleGuestAuth(c *gin.Context) {
 	acc, err := s.accounts.ProvisionGuest(c.Request.Context())