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
}

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 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 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
}