notification

type Deps struct {
	// Bot returns the current bot client; the initialize subsystem recreates
	// it when the Telegram configuration changes, so it is read per call.
	// nil means the bot is not configured.
	Bot func() *tgbot.Bot
	// GroupChatID returns the validated administrators' group chat id; zero
	// means no group is available and every group feature stays off. Read
	// per call for the same reason as Bot.
	GroupChatID func() int64
	// Topics maps forum topics in the administrators' group to the
	// conversation each carries.
	Topics        repository.TelegramTopicRepo
	Redis         *redis.Client
	Users         repository.UserRepo
	UserAuth      repository.UserAuthRepo
	UserCache     repository.UserCacheRepo
	Tickets       repository.TicketRepo
	Orders        repository.OrderRepo
	Subscriptions repository.UserSubscriptionRepo
	Plans         repository.SubscribeRepo
	Logs          repository.LogRepo
	// Wallet is the billing-domain read port for balance display.
	Wallet repository.WalletRepo
}

type Service interface {
	// HandleTelegramUpdate processes one bot update (command dispatch,
	// binding, admin actions). The polling loop calls it with the update the
	// bot library already decoded.
	HandleTelegramUpdate(ctx context.Context, update *models.Update)
	// HandleTelegramWebhook decodes one webhook payload and processes it.
	// The decode lives behind this facade so the bot library's update type
	// never crosses into the HTTP layer.
	HandleTelegramWebhook(ctx context.Context, payload []byte) error
	// NotifyTelegramUnbind sends the best-effort unbind notice to the chat.
	NotifyTelegramUnbind(userID, chatID int64) error
	// NotifyTelegramUser sends already-rendered MarkdownV2 text to the
	// user's bound Telegram chat; render it with RenderTelegramMarkdown so
	// the data is escaped. It reports an error when the user has no binding
	// or the bot is unconfigured, which callers treat as "nothing to
	// deliver".
	NotifyTelegramUser(ctx context.Context, userID int64, text string) error
	// PublishTelegramCommands registers the command menu every user sees.
	// The bot initialiser calls it once the client is ready, so the composer
	// offers the commands instead of leaving users to guess them.
	PublishTelegramCommands() error
	// SetupTelegramGroup validates the configured administrators' group
	// (forum supergroup, bot manages topics), prepares the notification
	// topic and publishes the group-scoped administrator menu. A zero group
	// id is a no-op; the caller disables group features when this errors.
	SetupTelegramGroup(ctx context.Context) error
	// NotifyAdminsTelegram posts already-rendered MarkdownV2 text (use
	// RenderTelegramMarkdown) into the administrators' notification topic.
	// It reports an error when the group is unavailable, which callers
	// treat as "nothing to deliver".
	NotifyAdminsTelegram(ctx context.Context, text string) error
	// NotifyTicketCreated opens a forum topic for a new website ticket.
	NotifyTicketCreated(ctx context.Context, t *ticket.Ticket) error
	// NotifyTicketReplied posts a website-side ticket reply into the
	// ticket's topic; tickets without a topic are skipped silently.
	NotifyTicketReplied(ctx context.Context, ticketID int64, from, content string) error
	// NotifyTicketStatusChanged mirrors a website-side status change onto
	// the ticket's topic (close/reopen).
	NotifyTicketStatusChanged(ctx context.Context, ticketID int64, status uint8) error
}