platform

type Action struct {
	Label            string `json:"label"`                      // user-visible text (Telegram button text / WhatsApp reply title)
	ID               string `json:"id"`                         // stable identifier (Telegram callback_data / WhatsApp reply id)
	URL              string `json:"url"`                        // set for link actions
	CopyText         string `json:"copyText,omitempty"`         // text copied by a platform-native copy action
	InlineQuery      string `json:"inlineQuery,omitempty"`      // query prefilled by a platform-native inline-share action
	OpensInlineQuery bool   `json:"opensInlineQuery,omitempty"` // true for a platform-native action that opens inline mode
}

type AddrPlatform interface {
	Platform

	// StartAt boots this platform's emulated API server bound to addr (e.g.
	// "127.0.0.1:54321"). It returns an error if addr cannot be bound (e.g.
	// already in use) instead of panicking, so the caller can surface it
	// through the test.
	StartAt(addr string) (Emulator, error)
}

type ChosenInlineResultEmulator interface {
	SelectInlineQueryResult(user User, queryID, resultID string) (inlineMessageID string, err error)
	WaitForInlineResultEdit(
		inlineMessageID string,
		afterVersion int,
		timeout time.Duration,
	) (*InlineQueryResult, int, bool)
}

type Direction string

type Emulator interface {
	// BotAPIURL is the base URL the bot-under-test must use for this platform's
	// API, in place of the real one (api.telegram.org, graph.facebook.com, ...).
	BotAPIURL() string

	// Close shuts the emulator's HTTP server down.
	Close()

	// SetWebhook registers the URL (and the HTTP client used to reach it) the
	// emulator pushes updates to, as the bot-under-test's webhook. Passing an
	// empty url clears it. On platforms that support polling (Telegram),
	// Submit* calls queue updates for getUpdates instead of failing while no
	// webhook is set; platforms that don't (WhatsApp) return an error from
	// Submit* until one is set — mirroring how a real bot token is either
	// webhook- or polling-driven, never both, and WhatsApp's Cloud API has no
	// polling mode at all.
	SetWebhook(url string, client *http.Client)

	// SubmitText delivers a user's text message from user in chatID to the
	// bot-under-test: it reserves the message's ID from chatID's shared
	// per-chat sequence, journals the inbound event, builds the
	// platform-native update, and delivers it via the configured strategy.
	// The returned error reports only a delivery failure (e.g. the webhook
	// responded with an error status, or no delivery strategy is available);
	// it is not a scenario assertion.
	SubmitText(chatID int64, user User, text string) error

	// SubmitClick delivers a user activating an interactive action (button
	// click) with the given callback data on the bot message identified by
	// targetMessageID. A callback query does not occupy its own slot in the
	// per-chat message-ID sequence.
	SubmitClick(chatID int64, user User, data string, targetMessageID int) error

	// WaitForMessage waits up to timeout for the (consumed+1)-th outbound bot
	// message to chatID, returning it normalized, or false on timeout.
	WaitForMessage(chatID int64, consumed int, timeout time.Duration) (*Message, bool)

	// WaitForEdit waits up to timeout for the message identified by
	// (chatID, messageID) to be edited past afterVersion (i.e. Version >
	// afterVersion), returning its new content normalized, or false on timeout.
	// Platforms with no message-edit capability may return false immediately.
	WaitForEdit(chatID int64, messageID int, afterVersion int, timeout time.Duration) (*Message, bool)

	// Transcript renders a chronological, human-readable dump of everything
	// recorded for chatID — inbound and outbound alike, edits shown as their
	// current version — for inclusion in assertion failure messages.
	Transcript(chatID int64) string

	// Journal returns chatID's chronological, structured journal entries —
	// the same events Transcript renders as prose, given directly to callers
	// (the observe package's Engine, diagnostics) that need to reason about
	// them structurally. An implementation that cannot produce a structured
	// journal returns a clear not-supported error and a nil slice.
	Journal(chatID int64) ([]JournalEntry, error)
}

type InlineQueryAnswer struct {
	QueryID    string              `json:"queryId"`
	Results    []InlineQueryResult `json:"results"`
	CacheTime  int                 `json:"cacheTime,omitempty"`
	IsPersonal bool                `json:"isPersonal,omitempty"`
	NextOffset string              `json:"nextOffset,omitempty"`
}

type InlineQueryEmulator interface {
	// SubmitInlineQuery delivers an inline query and returns its platform query
	// identifier. The result is observed separately via WaitForInlineQueryAnswer.
	SubmitInlineQuery(user User, query, offset string) (queryID string, err error)

	// WaitForInlineQueryAnswer waits for the bot's answer to queryID.
	WaitForInlineQueryAnswer(queryID string, timeout time.Duration) (*InlineQueryAnswer, bool)
}

type InlineQueryResult struct {
	Type         string     `json:"type"`
	ID           string     `json:"id"`
	Title        string     `json:"title,omitempty"`
	Description  string     `json:"description,omitempty"`
	Text         string     `json:"text,omitempty"`
	PhotoURL     string     `json:"photoUrl,omitempty"`
	ThumbnailURL string     `json:"thumbnailUrl,omitempty"`
	Caption      string     `json:"caption,omitempty"`
	Actions      [][]Action `json:"actions,omitempty"`
}

type JournalEntry struct {
	Direction    Direction        `json:"direction"`
	Kind         JournalEntryKind `json:"kind"`
	MessageID    int              `json:"messageId"`    // logical message identity, shared by inbound/outbound entries in this chat; 0 when Kind has no message identity of its own
	RefMessageID int              `json:"refMessageId"` // JournalEntryAction only: the message the action targeted
	Version      int              `json:"version"`      // JournalEntryMessage only: 0 = original send/inbound, N = the Nth edit
	Text         string           `json:"text"`
	Actions      [][]Action       `json:"actions"` // JournalEntryMessage only: actions attached to this entry, in platform row/col layout
	Method       string           `json:"method"`  // JournalEntryUncaptured only: the Bot API method name that was called
	At           time.Time        `json:"at"`

	// FromID is the platform-native identity of this entry's originator:
	// the Telegram user id of the client actor for a client-originated
	// entry, or the bot's own id for a bot-originated entry. It is 0 when
	// no identity is available (e.g. a pure method-call record with no
	// resolvable sender) — a Platform never invents an identity it does not
	// actually know. This is what lets a run-bundle roster (see
	// chatwright.dev/sdk's Actor.PlatformIdentities) attribute every journal
	// entry to whoever produced it.
	FromID int64 `json:"fromId"`
}

type JournalEntryKind string

type Message struct {
	Platform   string
	ChatID     int64
	MessageID  int // id the platform assigned to this outbound message
	Text       string
	Actions    [][]Action
	ReceivedAt time.Time
	Version    int // 0 for the original send; incremented on each in-place edit
}

type Platform interface {
	// Name is the platform's short identifier, e.g. "telegram" or "whatsapp".
	Name() string

	// Start boots this platform's emulated API server.
	Start() Emulator
}

type User struct {
	ID           int64
	FirstName    string
	LastName     string
	Username     string
	LanguageCode string
}