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 (admin use, wired in
  // Stage 10). delivered is false when the user has not started the bot.
  rpc SendToUser(SendToUserRequest) returns (SendResponse);
  // SendToGameChannel posts an arbitrary text message to the bot's configured
  // game channel (admin use, wired in Stage 10); the channel id lives 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 language.
message ValidateInitDataResponse {
  string external_id = 1;
  string username = 2;
  string first_name = 3;
  string language_code = 4;
}

// 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) selects 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.
message SendToUserRequest {
  string external_id = 1;
  string text = 2;
}

// SendToGameChannelRequest is an admin text message to the configured game channel.
message SendToGameChannelRequest {
  string text = 1;
}

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