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.

platform/telegram/internal/connector/server.go

@@ -0,0 +1,114 @@
+// Package connector implements the Telegram gRPC service (pkg/proto/telegram/v1):
+// the gateway calls ValidateInitData (Mini App auth) and Notify (out-of-app push);
+// the admin surface (Stage 10) will call SendToUser and SendToGameChannel. The
+// generic methods address a recipient by the identity external_id, so a future
+// platform connector can implement the same service.
+package connector
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+
+	"go.uber.org/zap"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+
+	telegramv1 "scrabble/pkg/proto/telegram/v1"
+	"scrabble/platform/telegram/internal/initdata"
+	"scrabble/platform/telegram/internal/render"
+)
+
+// Sender delivers Telegram messages to a chat. *bot.Bot implements it.
+type Sender interface {
+	// Notify sends a notification with a Mini App launch button to chatID.
+	Notify(ctx context.Context, chatID int64, text, buttonText, startParam string) error
+	// SendText sends a plain text message to chatID.
+	SendText(ctx context.Context, chatID int64, text string) error
+}
+
+// Server implements telegramv1.TelegramServer.
+type Server struct {
+	telegramv1.UnimplementedTelegramServer
+	validator initdata.Validator
+	sender    Sender
+	channelID int64
+	log       *zap.Logger
+}
+
+// NewServer builds the gRPC service from a validator (for ValidateInitData), a
+// sender (the bot), and the configured game channel id (0 disables channel posts).
+func NewServer(validator initdata.Validator, sender Sender, channelID int64, log *zap.Logger) *Server {
+	if log == nil {
+		log = zap.NewNop()
+	}
+	return &Server{validator: validator, sender: sender, channelID: channelID, log: log}
+}
+
+// ValidateInitData verifies Mini App launch data and returns the user identity.
+func (s *Server) ValidateInitData(ctx context.Context, req *telegramv1.ValidateInitDataRequest) (*telegramv1.ValidateInitDataResponse, error) {
+	u, err := s.validator.Validate(req.GetInitData())
+	if err != nil {
+		return nil, status.Error(codes.InvalidArgument, err.Error())
+	}
+	return &telegramv1.ValidateInitDataResponse{
+		ExternalId:   u.ExternalID,
+		Username:     u.Username,
+		FirstName:    u.FirstName,
+		LanguageCode: u.LanguageCode,
+	}, nil
+}
+
+// Notify renders and delivers an out-of-app notification. It reports
+// delivered=false (without an error) for a kind that is not pushed out-of-app or a
+// delivery the bot could not complete (e.g. the user never started the bot), so the
+// gateway treats a fallback miss as best-effort.
+func (s *Server) Notify(ctx context.Context, req *telegramv1.NotifyRequest) (*telegramv1.NotifyResponse, error) {
+	msg, ok := render.Render(req.GetKind(), req.GetPayload(), req.GetLanguage())
+	if !ok {
+		return &telegramv1.NotifyResponse{Delivered: false}, nil
+	}
+	chat, err := parseChatID(req.GetExternalId())
+	if err != nil {
+		return nil, status.Error(codes.InvalidArgument, err.Error())
+	}
+	if err := s.sender.Notify(ctx, chat, msg.Text, msg.ButtonText, msg.StartParam); err != nil {
+		s.log.Warn("notify delivery failed", zap.String("kind", req.GetKind()), zap.Error(err))
+		return &telegramv1.NotifyResponse{Delivered: false}, nil
+	}
+	return &telegramv1.NotifyResponse{Delivered: true}, nil
+}
+
+// SendToUser sends an arbitrary admin message to one user.
+func (s *Server) SendToUser(ctx context.Context, req *telegramv1.SendToUserRequest) (*telegramv1.SendResponse, error) {
+	chat, err := parseChatID(req.GetExternalId())
+	if err != nil {
+		return nil, status.Error(codes.InvalidArgument, err.Error())
+	}
+	if err := s.sender.SendText(ctx, chat, req.GetText()); err != nil {
+		s.log.Warn("send to user failed", zap.Error(err))
+		return &telegramv1.SendResponse{Delivered: false}, nil
+	}
+	return &telegramv1.SendResponse{Delivered: true}, nil
+}
+
+// SendToGameChannel posts an admin message to the configured game channel.
+func (s *Server) SendToGameChannel(ctx context.Context, req *telegramv1.SendToGameChannelRequest) (*telegramv1.SendResponse, error) {
+	if s.channelID == 0 {
+		return nil, status.Error(codes.FailedPrecondition, "game channel is not configured")
+	}
+	if err := s.sender.SendText(ctx, s.channelID, req.GetText()); err != nil {
+		s.log.Warn("send to channel failed", zap.Error(err))
+		return &telegramv1.SendResponse{Delivered: false}, nil
+	}
+	return &telegramv1.SendResponse{Delivered: true}, nil
+}
+
+// parseChatID converts a Telegram identity external_id into a numeric chat id.
+func parseChatID(externalID string) (int64, error) {
+	id, err := strconv.ParseInt(externalID, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("invalid external_id %q", externalID)
+	}
+	return id, nil
+}

platform/telegram/internal/connector/server_test.go

@@ -0,0 +1,155 @@
+package connector
+
+import (
+	"context"
+	"testing"
+
+	flatbuffers "github.com/google/flatbuffers/go"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+
+	"scrabble/pkg/fbs/scrabblefb"
+	telegramv1 "scrabble/pkg/proto/telegram/v1"
+	"scrabble/platform/telegram/internal/initdata"
+)
+
+// stubValidator returns a fixed user / error from Validate.
+type stubValidator struct {
+	user initdata.User
+	err  error
+}
+
+func (s stubValidator) Validate(string) (initdata.User, error) { return s.user, s.err }
+
+// fakeSender records the delivery calls the server makes.
+type fakeSender struct {
+	notify []notifyCall
+	text   []textCall
+	err    error
+}
+
+type notifyCall struct {
+	chatID                       int64
+	text, buttonText, startParam string
+}
+type textCall struct {
+	chatID int64
+	text   string
+}
+
+func (f *fakeSender) Notify(_ context.Context, chatID int64, text, buttonText, startParam string) error {
+	f.notify = append(f.notify, notifyCall{chatID, text, buttonText, startParam})
+	return f.err
+}
+
+func (f *fakeSender) SendText(_ context.Context, chatID int64, text string) error {
+	f.text = append(f.text, textCall{chatID, text})
+	return f.err
+}
+
+func yourTurnPayload(gameID string) []byte {
+	b := flatbuffers.NewBuilder(0)
+	gid := b.CreateString(gameID)
+	scrabblefb.YourTurnEventStart(b)
+	scrabblefb.YourTurnEventAddGameId(b, gid)
+	b.Finish(scrabblefb.YourTurnEventEnd(b))
+	return b.FinishedBytes()
+}
+
+func TestValidateInitData(t *testing.T) {
+	want := initdata.User{ExternalID: "42", Username: "neo", FirstName: "Thomas", LanguageCode: "ru"}
+	srv := NewServer(stubValidator{user: want}, &fakeSender{}, 0, nil)
+	resp, err := srv.ValidateInitData(context.Background(), &telegramv1.ValidateInitDataRequest{InitData: "x"})
+	if err != nil {
+		t.Fatalf("validate: %v", err)
+	}
+	if resp.GetExternalId() != "42" || resp.GetUsername() != "neo" || resp.GetFirstName() != "Thomas" || resp.GetLanguageCode() != "ru" {
+		t.Errorf("resp = %+v, want %+v", resp, want)
+	}
+
+	bad := NewServer(stubValidator{err: initdata.ErrInvalidInitData}, &fakeSender{}, 0, nil)
+	if _, err := bad.ValidateInitData(context.Background(), &telegramv1.ValidateInitDataRequest{}); status.Code(err) != codes.InvalidArgument {
+		t.Errorf("err code = %v, want InvalidArgument", status.Code(err))
+	}
+}
+
+func TestNotifyDelivers(t *testing.T) {
+	const gameID = "7c9e6679-7425-40de-944b-e07fc1f90ae7"
+	sender := &fakeSender{}
+	srv := NewServer(stubValidator{}, sender, 0, nil)
+	resp, err := srv.Notify(context.Background(), &telegramv1.NotifyRequest{
+		ExternalId: "12345", Kind: "your_turn", Payload: yourTurnPayload(gameID), Language: "en",
+	})
+	if err != nil {
+		t.Fatalf("notify: %v", err)
+	}
+	if !resp.GetDelivered() {
+		t.Fatal("expected delivered=true")
+	}
+	if len(sender.notify) != 1 {
+		t.Fatalf("notify calls = %d, want 1", len(sender.notify))
+	}
+	if got := sender.notify[0]; got.chatID != 12345 || got.startParam != "g"+gameID {
+		t.Errorf("notify call = %+v, want chatID 12345 startParam g%s", got, gameID)
+	}
+}
+
+func TestNotifySkipsUnrenderedKind(t *testing.T) {
+	sender := &fakeSender{}
+	srv := NewServer(stubValidator{}, sender, 0, nil)
+	resp, err := srv.Notify(context.Background(), &telegramv1.NotifyRequest{
+		ExternalId: "12345", Kind: "opponent_moved", Language: "en",
+	})
+	if err != nil {
+		t.Fatalf("notify: %v", err)
+	}
+	if resp.GetDelivered() {
+		t.Error("expected delivered=false for an unrendered kind")
+	}
+	if len(sender.notify) != 0 {
+		t.Errorf("sender called %d times, want 0", len(sender.notify))
+	}
+}
+
+func TestNotifyInvalidExternalID(t *testing.T) {
+	srv := NewServer(stubValidator{}, &fakeSender{}, 0, nil)
+	_, err := srv.Notify(context.Background(), &telegramv1.NotifyRequest{
+		ExternalId: "not-a-number", Kind: "your_turn", Payload: yourTurnPayload("g"), Language: "en",
+	})
+	if status.Code(err) != codes.InvalidArgument {
+		t.Errorf("err code = %v, want InvalidArgument", status.Code(err))
+	}
+}
+
+func TestSendToUser(t *testing.T) {
+	sender := &fakeSender{}
+	srv := NewServer(stubValidator{}, sender, 0, nil)
+	resp, err := srv.SendToUser(context.Background(), &telegramv1.SendToUserRequest{ExternalId: "999", Text: "hi"})
+	if err != nil {
+		t.Fatalf("send to user: %v", err)
+	}
+	if !resp.GetDelivered() || len(sender.text) != 1 || sender.text[0].chatID != 999 || sender.text[0].text != "hi" {
+		t.Errorf("send to user = %v / calls %+v", resp.GetDelivered(), sender.text)
+	}
+}
+
+func TestSendToGameChannel(t *testing.T) {
+	t.Run("unconfigured", func(t *testing.T) {
+		srv := NewServer(stubValidator{}, &fakeSender{}, 0, nil)
+		_, err := srv.SendToGameChannel(context.Background(), &telegramv1.SendToGameChannelRequest{Text: "x"})
+		if status.Code(err) != codes.FailedPrecondition {
+			t.Errorf("err code = %v, want FailedPrecondition", status.Code(err))
+		}
+	})
+	t.Run("configured", func(t *testing.T) {
+		sender := &fakeSender{}
+		srv := NewServer(stubValidator{}, sender, 555, nil)
+		resp, err := srv.SendToGameChannel(context.Background(), &telegramv1.SendToGameChannelRequest{Text: "news"})
+		if err != nil {
+			t.Fatalf("send to channel: %v", err)
+		}
+		if !resp.GetDelivered() || len(sender.text) != 1 || sender.text[0].chatID != 555 {
+			t.Errorf("send to channel calls = %+v", sender.text)
+		}
+	})
+}