scrabble-game/pkg/proto/telegram/v1/telegram.proto

syntax = "proto3";

// Package scrabble.telegram.v1 is the RPC contract of the Telegram platform
// side-service (the "connector"). The connector holds the bot token and is the
// only component that talks to the Telegram Bot API; gateway and backend reach it
// over plain gRPC on the trusted internal network (ARCHITECTURE.md §1, §12).
//
// The generic delivery methods (Notify, SendToUser, SendToGameChannel) are
// platform-agnostic: they address a recipient by the identity external_id (as in
// the backend identities table), so a future VK / MAX connector can implement the
// same service. ValidateInitData is the one Telegram-specific method (it parses
// Telegram Web App launch data); it is kept here for now.
package scrabble.telegram.v1;

option go_package = "scrabble/pkg/proto/telegram/v1;telegramv1";

// Telegram is the connector RPC surface.
service Telegram {
  // ValidateInitData verifies Telegram Mini App launch data (HMAC) and returns
  // the authenticated user. The gateway calls it during the auth.telegram edge
  // operation, then provisions the session through the backend internal API.
  rpc ValidateInitData(ValidateInitDataRequest) returns (ValidateInitDataResponse);
  // ValidateLoginWidget verifies Telegram Login Widget authorization data (the web
  // sign-in flow, HMAC under SHA-256(bot_token)) and returns the authenticated
  // user. The gateway calls it during the link.telegram edge operation to attach a
  // Telegram identity to an existing account (Stage 11).
  rpc ValidateLoginWidget(ValidateLoginWidgetRequest) returns (ValidateLoginWidgetResponse);
  // Notify delivers an out-of-app notification for a backend push event. The
  // gateway calls it only for a recipient with no live in-app stream (so the
  // platform push never duplicates in-app delivery). The connector renders a
  // localized message with a Mini App deep-link button from the FlatBuffers
  // payload; unrenderable kinds are skipped (delivered=false).
  rpc Notify(NotifyRequest) returns (NotifyResponse);
  // SendToUser sends an arbitrary text message to one user through the bot the
  // request selects by language (admin use, wired in Stage 10). delivered is false
  // when the user has not started that bot.
  rpc SendToUser(SendToUserRequest) returns (SendResponse);
  // SendToGameChannel posts an arbitrary text message to the game channel of the
  // bot the request selects by language (admin use, wired in Stage 10); the channel
  // ids live only in the connector configuration.
  rpc SendToGameChannel(SendToGameChannelRequest) returns (SendResponse);
}

// ValidateInitDataRequest carries the raw Telegram Web App initData string.
message ValidateInitDataRequest {
  string init_data = 1;
}

// ValidateInitDataResponse is the validated identity. external_id is the Telegram
// user id used as the identities external_id; language_code seeds a new account's
// preferred (interface) language. service_language (en/ru) is the language tag of
// the bot that validated the launch data; it is persisted per account and routes
// the user's out-of-app push back through the right bot (it is NOT the game's
// language). supported_languages is that bot's set of offered game languages
// (subset of {en, ru}, at least one — a singleton for a single-language bot); the
// UI gates the New Game variant choice by it.
message ValidateInitDataResponse {
  string external_id = 1;
  string username = 2;
  string first_name = 3;
  string language_code = 4;
  string service_language = 5;
  repeated string supported_languages = 6;
}

// ValidateLoginWidgetRequest carries the Login Widget result serialized as a URL
// query string (the widget fields plus the hash, e.g. "auth_date=...&id=...&hash=...").
message ValidateLoginWidgetRequest {
  string data = 1;
}

// ValidateLoginWidgetResponse is the validated identity. external_id is the
// Telegram user id used as the identities external_id. The Login Widget carries no
// language_code (unlike Mini App initData).
message ValidateLoginWidgetResponse {
  string external_id = 1;
  string username = 2;
  string first_name = 3;
}

// NotifyRequest addresses a push event to one recipient. kind is the backend push
// catalog kind (your_turn, nudge, match_found, notify); payload is the FlatBuffers
// scrabblefb.* body for that kind; language (en/ru) is the recipient's service
// language (from their last ValidateInitData) — it both selects the delivering bot
// and the message template.
message NotifyRequest {
  string external_id = 1;
  string kind = 2;
  bytes payload = 3;
  string language = 4;
}

// NotifyResponse reports whether a message was actually sent (false when the kind
// is not rendered out-of-app or the user has not started the bot).
message NotifyResponse {
  bool delivered = 1;
}

// SendToUserRequest is an admin text message to one user by external_id. language
// (en/ru) selects which bot delivers it — an operator choice in the admin console,
// unrelated to the user's service language.
message SendToUserRequest {
  string external_id = 1;
  string text = 2;
  string language = 3;
}

// SendToGameChannelRequest is an admin text message to a game channel. language
// (en/ru) selects which bot's configured channel receives it — an operator choice
// in the admin console.
message SendToGameChannelRequest {
  string text = 1;
  string language = 2;
}

// SendResponse reports whether the message was sent.
message SendResponse {
  bool delivered = 1;
}