104 lines
4.4 KiB
Protocol Buffer
104 lines
4.4 KiB
Protocol Buffer
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;
|
|
}
|