botsfw

type AppContext interface {
	i18n.LocalesProvider
	GetTranslator(ctx context.Context) i18n.Translator
}

type BotCommand struct {
	Command     string `json:"command"`     // Text of the command; 1-32 characters. Can contain only lowercase English letters, digits and underscores.
	Description string `json:"description"` // Description of the command; 1-256 characters.
	IsEphemeral bool   `json:"is_ephemeral,omitempty"`
}

type BotCommandOrder string

type BotContext struct {
	AppContext  AppContext
	BotHost     BotHost      // describes current bot app host environment
	BotSettings *BotSettings // keeps parameters of a bot that are static and are not changed in runtime
}

type BotContextProvider interface {
	// GetBotContext returns BotContext by platformID & botID
	GetBotContext(ctx context.Context, platformID botsfwconst.Platform, botID string) (botContext *BotContext, err error)
}

type BotHost interface {

	// Context returns a context.Context for a request. We need this as some platforms (as Google App Engine Standard)
	// require usage of a context with a specific wrapper
	Context(r *http.Request) context.Context

	// GetHTTPClient returns HTTP client for current host
	// We need this as some platforms (as Google App Engine Standard) require setting http client in a specific way.
	GetHTTPClient(c context.Context) *http.Client
}

type BotInputProvider interface {
	// Input returns a webhook input from a specific bot interface (Telegram, FB Messenger, Viber, etc.)
	Input() botinput.InputMessage
}

type BotPlatform interface {

	// ID returns bot platform ID like 'telegram', 'fbmessenger', 'viber', etc.
	ID() string

	// Version returns a version of a bot platform adapter. It is used for debugging purposes.
	Version() string
}

type BotProfile interface {
	ID() string
	Router() Router
	DefaultLocale() i18n.Locale
	SupportedLocales() []i18n.Locale
	NewBotChatData() botsfwmodels.BotChatData
	NewPlatformUserData() botsfwmodels.PlatformUserData
	GetTranslations() BotTranslations
}

type BotProfileOption func(*botProfileConfig)

type BotRecordsFieldsSetter interface {

	// Platform returns platform name, e.g. 'telegram', 'fbmessenger', etc.
	// This method is for debug pruposes and to indicate that different platforms may have different fields
	// Though '*' can be used for a generic setter that works for all platforms
	// If both '*' and platform specific setters are defined, the generic setter will be used first.
	Platform() string

	// SetBotUserFields sets fields of bot user record
	SetBotUserFields(botUser botsfwmodels.PlatformUserData, sender botinput.Sender, botID, botUserID, appUserID string) error

	// SetBotChatFields sets fields of bot botChat record
	// TODO: document isAccessGranted parameter
	SetBotChatFields(botChat botsfwmodels.BotChatData, chat botinput.Chat, botID, botUserID, appUserID string, isAccessGranted bool) error
}

type BotSettings struct {

	// Platform is a platform that bot is running on
	// E.g.: Telegram, Viber, Facebook Messenger, WhatsApp, etc.
	Platform botsfwconst.Platform

	// Env is an environment where bot is running
	// E.g.: Production/Live, Local/Dev, Staging, etc.
	Env string

	// Profile is a bot profile that defines bot's behavior
	// It includes commands router and some other settings
	// More in BotProfile documentation.
	Profile BotProfile

	// Code is a human-readable ID of a bot.
	// When displayed it is usually prefixed with @.
	// For example:
	//   - @listus_bot for https://t.me/listus_bot
	Code string

	// ID is a bot-platform ID of a bot. For example, it could be a GUID.
	// Not all platforms use it. For example Telegram doesn't use it.
	ID string

	// Token is used to authenticate bot with a platform when it is not responding to a webhook
	// but calling platform APIs directly.
	Token string

	// PaymentToken is used to process payments on bot platform
	PaymentToken string

	// PaymentTestToken is used to process test payments on bot platform
	PaymentTestToken string

	// VerifyToken is used by Facebook Messenger - TODO: Document how it is used and add a link to Facebook docs
	VerifyToken string

	// GAToken is Google Analytics token - TODO: Refactor tu support multiple or move out
	GAToken string

	// WebhookSecretToken is the secret Telegram (or other platform) sends back on every
	// webhook call in the `X-Telegram-Bot-Api-Secret-Token` header (set via `secret_token`
	// when registering the webhook, e.g. Telegram's `setWebhook`). Webhook handlers MUST
	// verify this value (constant-time) before processing an update, otherwise anyone who
	// knows the bot's webhook URL can POST forged updates and impersonate any platform user.
	//
	// If left empty, no verification is possible for this bot - this is a backward-compat
	// escape hatch for existing deployments, not a recommended posture. See
	// RequireWebhookSecret to make an empty secret a hard failure instead.
	WebhookSecretToken string

	// RequireWebhookSecret, when true, tells a webhook handler to reject all requests for
	// this bot (rather than just logging a warning) if WebhookSecretToken is empty. Defaults
	// to false (off) so existing deployments that haven't configured a secret yet keep
	// working, but every bot SHOULD set WebhookSecretToken and flip this to true.
	RequireWebhookSecret bool

	// Locale is a default locale for a bot.
	// While a bot profile can support multiple locales a bot can be dedicated to a specific country/language
	Locale i18n.Locale

	// Store owns framework identity and chat state for this bot. It is a narrow
	// use-case port, never a generic database handle.
	Store botsfwstore.StateStore

	// UserErrorDetails controls whether technical command-processing errors are
	// available to the user. The zero value preserves the legacy presentation.
	//
	// This is deliberately a per-bot opt-in. A host that accepts the disclosure
	// risk can select an expandable, same-message presentation without changing
	// the policy of every bot served by the same framework process.
	UserErrorDetails UserErrorDetailsPolicy
}

type BotSettingsBy struct {

	// ByCode keeps settings by bot code - it is a human-readable ID of a bot.
	//
	// Deprecated: ambiguous once more than one platform is in play, because the
	// same code may legitimately be used for the same product on Telegram and on
	// WhatsApp. First registration wins here. Use ByPlatformAndCode, or resolve
	// via BotContextProvider.GetBotContext which is platform-scoped.
	ByCode map[string]*BotSettings

	// ByID keeps settings by bot ID - it is a machine-readable ID of a bot.
	//
	// Deprecated: ambiguous across platforms, as ByCode. Use ByPlatformAndID.
	ByID map[string]*BotSettings

	ByProfile map[string][]*BotSettings

	// ByPlatformAndCode keeps settings by platform, then bot code.
	//
	// Bot codes are only unique WITHIN a platform: "debtus" on Telegram and
	// "debtus" on WhatsApp are different bots with different tokens.
	ByPlatformAndCode map[botsfwconst.Platform]map[string]*BotSettings

	// ByPlatformAndID keeps settings by platform, then bot ID.
	ByPlatformAndID map[botsfwconst.Platform]map[string]*BotSettings
}

type BotSettingsProvider func(ctx context.Context) BotSettingsBy

type BotState interface {
	IsNewerThen(chatEntity botsfwmodels.BotChatData) bool
}

type BotTranslations struct {
	Description      string
	ShortDescription string
	Commands         []BotCommand
}

type BotUserCreator func(c context.Context, botID string, apiUser botinput.Actor) (botsfwmodels.PlatformUserData, error)

type CallbackAction func(whc WebhookContext, callbackUrl *url.URL) (m botmsg.MessageFromBot, err error)

type CallbackQueryAcknowledger interface {
	AcknowledgeCallbackQuery(text string, showAlert bool) error
	WasCallbackQueryAcknowledged() bool
}

type CapabilityID string

type ChosenInlineResultAction func(whc WebhookContext, chosenResult botinput.ChosenInlineResult, queryUrl *url.URL) (m botmsg.MessageFromBot, err error)

type ChosenInlineResultHandlerFunc func(whc WebhookContext, inlineQuery botinput.ChosenInlineResult) (handled bool, m botsfw2.MessageFromBot, err error)

type Command struct {
	Code       CommandCode
	InputTypes []botinput.Type // Instant match if != TypeUnknown && == whc.InputTypes()
	Icon       string
	Replies    []Command
	Title      string
	Titles     map[string]string
	ExactMatch string
	Commands   []string
	Matcher    CommandMatcher
	//
	Action                   CommandAction
	TextAction               TextAction
	StartAction              StartAction
	CallbackAction           CallbackAction
	LocationAction           LocationAction
	InlineQueryAction        InlineQueryAction
	ChosenInlineResultAction ChosenInlineResultAction
	PreCheckoutQueryAction   PreCheckoutQueryAction
	SuccessfulPaymentAction  SuccessfulPaymentAction
	RefundedPaymentAction
}

type CommandAction func(whc WebhookContext) (m botmsg.MessageFromBot, err error)

type CommandCode string

type CommandMatcher func(command Command, whc WebhookContext) bool

type CommandOwnership struct {
	Code               CommandCode
	Aliases            []CommandCode
	CallbackNamespaces []string
	InputTypes         []botinput.Type
}

type CommandResponseResponder interface {
	ResponderForCommand(CommandCode) WebhookResponder
}

type CreateWebhookContextArgs struct {
	HttpRequest  *http.Request // TODO: Can we get rid of it? Needed for botHost.GetHTTPClient()
	AppContext   AppContext
	BotContext   BotContext
	WebhookInput botinput.InputMessage
	Store        botsfwstore.StateStore
}

type EnvProvider interface {
	LookupEnv(name string) (value string, ok bool)
}

type EnvProviderFunc func(name string) (value string, ok bool)

type ErrAuthFailed string

type ExecutionContext interface {
	Context() context.Context
}

type FeatureMount struct {
	ID           string
	Mode         FeatureMountMode
	Namespace    string
	Navigator    NavigatorID
	Capabilities []CapabilityID
	Commands     []CommandOwnership
}

type FeatureMountMode string

type FeatureRegistry struct {
	// contains filtered or unexported fields
}

type FeatureScenario struct {
	Mount       FeatureMount
	Messages    []ScenarioMessage
	Navigation  []NavigatorID
	SideEffects []string
}

type FeatureScenarioContext struct {
	// contains filtered or unexported fields
}

type FeatureScenarioExpectation struct {
	Mode        FeatureMountMode
	Messages    int
	Paths       []ScenarioMessagePath
	Navigation  []NavigatorID
	SideEffects []string
	Policy      PresentationPolicy
}

type FeatureScenarioFlow func(*FeatureScenarioContext) error

type HttpRouter interface {
	Handle(method string, path string, handle http.HandlerFunc)
}

type InlineInputHandler struct {
	ProfileID                string // Not sure if we really need it
	HandleInlineQuery        InlineQueryHandlerFunc
	HandleChosenInlineResult ChosenInlineResultHandlerFunc
}

type InlineQueryAction func(whc WebhookContext, inlineQuery botinput.InlineQuery, queryUrl *url.URL) (m botmsg.MessageFromBot, err error)

type InlineQueryHandlerFunc func(whc WebhookContext, inlineQuery botinput.InlineQuery) (handled bool, m botsfw2.MessageFromBot, err error)

type InputMessage interface {
	Text() string
}

type LocationAction func(whc WebhookContext, latitude, longitude float64) (m botmsg.MessageFromBot, err error)

type MessengerResponse interface {
	GetMessageID() string
}

type NavigatorID string

type OnMessageSentResponse struct {
	StatusCode int
	Message    MessengerResponse // TODO: change to some interface
}

type PersistentBottomKeyboardPolicy string

type PreCheckoutQueryAction func(whc WebhookContext, preCheckout botinput.PreCheckoutQuery) (m botmsg.MessageFromBot, err error)

type PresentationPolicy struct {
	PersistentBottomKeyboard PersistentBottomKeyboardPolicy
}

type RefundedPaymentAction func(whc WebhookContext, payment botinput.RefundedPayment) (m botmsg.MessageFromBot, err error)

type Router interface {
	RegisterCommands(commands ...Command)
	RegisterCommandsForInputType(inputType botinput.Type, commands ...Command)

	// Dispatch requests to commands by input type, command code or a matching function
	Dispatch(webhookHandler WebhookHandler, responder WebhookResponder, whc WebhookContext) error

	// RegisteredCommands returns all registered commands
	RegisteredCommands() map[botinput.Type]map[CommandCode]Command

	// SetFallbackHandler registers a catch-all action for the given input type.
	// The fallback fires only when no registered command matches the input.
	// Unlike a catch-all Matcher command, the fallback is order-independent:
	// it is stored separately and never blocks the normal command-matching loop.
	// Only one fallback per input type is supported; a second call replaces the first.
	SetFallbackHandler(inputType botinput.Type, action CommandAction)
}

type RouterResponderProvider interface {
	GetRouterResponder(WebhookContext, WebhookResponder) WebhookResponder
}

type ScenarioMessage struct {
	Path    ScenarioMessagePath
	Message botmsg.MessageFromBot
}

type ScenarioMessagePath string

type SendGate interface {
	// CanSend reports whether m may be sent right now.
	//
	// A nil error means the send may proceed. A non-nil error means it may not,
	// and describes why; implementations should wrap ErrSendNotPermitted so the
	// refusal is classifiable.
	//
	// CanSend must not perform the send, and should avoid network calls: it is
	// consulted on every outbound message.
	CanSend(c context.Context, m botmsg.MessageFromBot) error
}

type StartAction TextAction

type SuccessfulPaymentAction func(whc WebhookContext, payment botinput.SuccessfulPayment) (m botmsg.MessageFromBot, err error)

type TextAction func(whc WebhookContext, text string) (m botmsg.MessageFromBot, err error)

type TranslatorProvider func(c context.Context) i18n.Translator

type UserErrorDetailsDisclosure string

type UserErrorDetailsPolicy struct {
	Disclosure UserErrorDetailsDisclosure
}

type WebhookAnalytics interface {
	Enqueue(message analytics.Message)
}

type WebhookContext interface {
	WebhookRequestContext
	WebhookInputContext
	WebhookUserData
	WebhookI18n
	WebhookMessaging
	WebhookTelemetry
}

type WebhookContextBase struct {
	// contains filtered or unexported fields
}

type WebhookDriver interface {
	RegisterWebhookHandlers(httpRouter HttpRouter, pathPrefix string, webhookHandlers ...WebhookHandler)
	HandleWebhook(w http.ResponseWriter, r *http.Request, webhookHandler WebhookHandler)
}

type WebhookHandler interface {

	// RegisterHttpHandlers registers HTTP handlers for bot API
	RegisterHttpHandlers(driver WebhookDriver, botHost BotHost, router HttpRouter, pathPrefix string)

	// HandleWebhookRequest handles incoming webhook request
	HandleWebhookRequest(w http.ResponseWriter, r *http.Request)

	// GetBotContextAndInputs returns bot context and inputs for current request
	// It returns multiple inputs as some platforms (like Facebook Messenger)
	// may send multiple message in one request
	GetBotContextAndInputs(c context.Context, r *http.Request) (botContext *BotContext, entriesWithInputs []botinput.EntryInputs, err error)

	// CreateWebhookContext creates WebhookContext for current webhook request
	CreateWebhookContext(args CreateWebhookContextArgs) (WebhookContext, error)

	GetResponder(w http.ResponseWriter, whc WebhookContext) WebhookResponder
	HandleUnmatched(whc WebhookContext) (m botsfw2.MessageFromBot)
}

type WebhookHandlerBase struct {
	WebhookDriver
	BotHost
	BotPlatform
	//RecordsMaker        botsfwmodels.BotRecordsMaker
	RecordsFieldsSetter BotRecordsFieldsSetter
	TranslatorProvider  TranslatorProvider
}

type WebhookI18n interface {
	i18n.SingleLocaleTranslator

	// SetLocale switches the active locale for this request.
	SetLocale(code5 string) error

	// GetTranslator returns a translator pinned to the given locale code.
	GetTranslator(locale string) i18n.SingleLocaleTranslator

	// CommandText formats a command title and icon into a display string.
	CommandText(title, icon string) string
}

type WebhookInlineQueryContext interface {
}

type WebhookInputContext interface {
	BotInputProvider

	// GetBotUserID returns the platform-specific user ID of the sender as a string.
	GetBotUserID() string

	// MustBotChatID returns the chat ID or panics if it cannot be determined.
	MustBotChatID() string

	// IsInGroup reports whether the message was received in a group chat.
	IsInGroup() (bool, error)
}

type WebhookMessaging interface {
	// NewMessage creates a plain-text MessageFromBot.
	NewMessage(text string) botmsg.MessageFromBot

	// NewMessageByCode creates a MessageFromBot from an i18n key, formatting it with args.
	NewMessageByCode(messageCode string, a ...interface{}) botmsg.MessageFromBot

	// NewEditMessage creates a MessageFromBot that edits the previously sent message.
	NewEditMessage(text string, format botmsg.Format) (botmsg.MessageFromBot, error)

	// Responder returns the WebhookResponder used to deliver messages to the platform.
	Responder() WebhookResponder
}

type WebhookNewContext struct {
	BotContext
	botinput.InputMessage
}

type WebhookRequestContext interface {
	// Context returns the Go context for this request.
	Context() context.Context

	// SetContext replaces the request context (e.g. after adding values or a deadline).
	SetContext(c context.Context)

	// Request returns the raw HTTP request.
	Request() *http.Request

	// Environment returns the deployment environment (e.g. "local", "production").
	Environment() string

	// BotPlatform returns the platform this request arrived on (Telegram, Viber, FBM, …).
	BotPlatform() BotPlatform

	// BotContext returns settings and host information for the current bot.
	BotContext() BotContext

	// GetBotCode is a convenience shortcut for BotContext().BotSettings.Code.
	GetBotCode() string

	// GetBotSettings is a convenience shortcut for BotContext().BotSettings.
	GetBotSettings() *BotSettings

	// AppContext returns application-level presentation context (for example i18n).
	AppContext() AppContext

	// ExecutionContext returns the execution context.
	// Deprecated: use Context() directly.
	ExecutionContext() ExecutionContext
}

type WebhookResponder interface {
	SendMessage(c context.Context, m botmsg.MessageFromBot, channel botmsg.BotAPISendMessageChannel) (response OnMessageSentResponse, err error)
	DeleteMessage(c context.Context, messageID string) (err error)
}

type WebhookTelemetry interface {
	Analytics() WebhookAnalytics
}

type WebhookUserData interface {
	// ChatData returns the current bot chat's persistent data.
	// Returns nil for input types that have no associated chat (e.g. InlineQuery).
	ChatData() botsfwmodels.BotChatData

	// SaveBotChat persists the current chat data to the database.
	SaveBotChat() error

	// GetBotUser returns the current platform user without exposing a storage record.
	GetBotUser() (botUser botsfwstore.PlatformUser, err error)

	// SetBotUserAccessGranted changes the platform-user access flag through the
	// injected state-store port.
	SetBotUserAccessGranted(value bool) error

	// AppUserID returns the application-layer user ID linked to this bot user.
	AppUserID() string

	// SetUser caches the resolved app user ID and data into the context.
	SetUser(id string, data botsfwmodels.AppUserData)

	// AppUserData loads and returns the app user's persistent data.
	AppUserData() (botsfwmodels.AppUserData, error)

	// RecordsFieldsSetter returns the helper used to populate new bot/chat/user records.
	RecordsFieldsSetter() BotRecordsFieldsSetter

	// UpdateLastProcessed records the message sequence number / timestamp on the chat entity.
	UpdateLastProcessed(chatEntity botsfwmodels.BotChatData) error

	// IsNewerThen reports whether the current message is newer than the chat entity's
	// last-processed sequence number (used to detect and discard duplicate deliveries).
	IsNewerThen(chatEntity botsfwmodels.BotChatData) bool
}