chatplatform

type Actor interface {
	// ReplyInThread posts content in a thread on the referenced message,
	// creating the thread if Ref.ThreadID is empty. Returns the thread's id.
	ReplyInThread(ctx context.Context, to Ref, threadName, content string) (ID, error)

	// React adds a reaction to the referenced message.
	React(ctx context.Context, to Ref, emoji string) error

	// ThreadHistory returns up to limit messages from a thread, oldest first.
	// Used to carry conversation context somewhere it can be read by people who
	// were never in the thread.
	ThreadHistory(ctx context.Context, threadID ID, limit int) ([]Message, error)
}

type Choice struct {
	// Key identifies the choice when it comes back. It is matched exactly, so
	// it must be stable across restarts — an interaction can arrive long after
	// the prompt was posted.
	Key string
	// Label is what the person reads.
	Label string
	Style ChoiceStyle
}

type ChoiceStyle int

type CommandOption struct {
	Name        string
	Description string
	Required    bool
}

type CommandSpec struct {
	Name        string
	Description string
	Options     []CommandOption
	// RequiredRoles restricts who may invoke the command, where the platform
	// can enforce it. A provider that cannot MUST still deliver the
	// interaction — the caller re-checks Interaction.By.Roles regardless,
	// because platform-side gating is a convenience and never the authority.
	RequiredRoles []ID
}

type Commands interface {
	// RegisterCommands declares the complete set, replacing whatever was
	// registered before.
	//
	// Declarative rather than incremental: it is idempotent, safe to run on
	// every start, and leaves no way for the registered set to drift from the
	// declared one. Partial updates are impossible by design.
	RegisterCommands(ctx context.Context, cmds []CommandSpec) error
}

type Config struct {
	// Token authenticates the bot.
	Token string

	// Space is the single guild, workspace or network this provider serves,
	// fixed here so no method has to take it — and so the contract never has to
	// choose one platform's word for the concept.
	Space ID

	// AllowedChannels is the exhaustive set of channels a Reader may emit from.
	// Empty means none. Providers enforce this themselves; a consumer must not
	// be able to reach past it.
	AllowedChannels []ID

	// ReadOnly asks for an observing provider. A provider MUST return a
	// Provider with a nil Actor when this is set, rather than an Actor that
	// refuses at call time — the point is that there is nothing to misuse.
	ReadOnly bool
}

type ConnState struct {
	Status Status

	// LastReconnectLostEvents reports whether the most recent reconnect started
	// a fresh session rather than resuming the previous one.
	//
	// A fresh session means every event buffered during the gap was DROPPED. For
	// a bot that answers questions, those are questions nobody will be answered
	// — a failure with no error, no crash and no trace. Nothing else surfaces
	// it, so the contract does.
	LastReconnectLostEvents bool

	// Since is when the current Status began.
	Since time.Time
}

type Factory func(Config) (*Provider, error)

type FieldSpec struct {
	// Key identifies the value when the form comes back.
	Key   string
	Label string
	// Value prefills the field. This is what lets a person see and edit exactly
	// what is about to be published on their behalf, rather than consenting to
	// something they have not read.
	Value     string
	Multiline bool
	Required  bool
	// MaxLen is an optional character limit. Zero means the platform's default.
	MaxLen int
}

type FormSpec struct {
	Title  string
	Fields []FieldSpec
}

type ID string

type Interaction struct {
	Type  InteractionType
	Token ResponseToken
	// Ref locates what was acted upon.
	Ref Ref
	// By is who acted. Authorisation is decided from By.Roles — never from a
	// claim in message content, and never from By.Name.
	By Member

	// ChoiceKey is set when Type is ChoiceSelected.
	ChoiceKey string
	// Values holds submitted fields when Type is FormSubmitted.
	Values map[string]string
	// Command and Args are set when Type is CommandInvoked.
	Command string
	Args    map[string]string
}

type InteractionType int

type Interactive interface {
	// Prompt posts a message offering choices, returning the message id.
	Prompt(ctx context.Context, to Ref, p PromptSpec) (ID, error)

	// OpenForm opens a form in response to an interaction. Most platforms only
	// permit this as a direct response, which is why it takes a token rather
	// than a Ref.
	OpenForm(ctx context.Context, tok ResponseToken, f FormSpec) error

	// Respond answers an interaction.
	Respond(ctx context.Context, tok ResponseToken, content string, ephemeral bool) error

	// UpdateSource replaces the message an interaction came from — a card
	// showing who actioned it, with the choices removed.
	//
	// Without this, buttons stay live after they have been used and a second
	// person actions the same thing. Passing nil choices removes them.
	UpdateSource(ctx context.Context, tok ResponseToken, content string, choices []Choice) error

	// Interactions yields interactions until the session ends.
	Interactions() <-chan Interaction
}

type Member struct {
	ID    ID
	Name  string
	Roles []ID
}

type MemberInspector interface {
	// Member returns a member's current identity and roles. Returns ErrNotFound
	// if they are not in the space.
	Member(ctx context.Context, userID ID) (Member, error)

	// MemberJoined returns when a member joined the space.
	MemberJoined(ctx context.Context, userID ID) (time.Time, error)
}

type Message struct {
	ID        ID
	ChannelID ID
	// ThreadID is empty when the message is not already in a thread.
	ThreadID ID
	// ParentID is the channel a thread hangs off, and is empty when the message
	// is not in a thread — so ChannelID is the channel to test in that case.
	//
	// It exists because ChannelAllowed admits a thread on behalf of its parent,
	// and a consumer that keeps its own allowlist cannot otherwise agree with
	// that decision: a thread's id is its own, never the configured one. Without
	// the parent, such a consumer must either drop every thread reply or accept
	// every one of them, and the second is not revocable — a channel removed
	// from the allowlist would keep leaking through its threads.
	//
	// Empty when the platform models threads as their own channels but the
	// parent could not be resolved. Treat that as "not permitted", matching
	// ChannelAllowed: an unresolvable parent is not evidence of permission.
	ParentID ID
	Content  string
	IsBot    bool
	Author   Member

	// Addressed reports that this message speaks to the bot directly: it
	// mentions the bot, or it replies to something the bot said.
	//
	// A boolean rather than a mention list, deliberately. A consumer that must
	// answer "was I spoken to" should not have to learn who else was mentioned,
	// nor parse a platform's mention syntax out of Content — which is where a
	// consumer picks up a dependency on the very wire format this contract
	// exists to hide.
	//
	// This is NOT mention resolution. Nothing user-controlled reaches the
	// consumer through it: no display names, no rendered markup, no list of
	// third parties. It is one fact the provider is uniquely able to establish,
	// because only the provider knows which account it authenticated as.
	//
	// False when the provider cannot determine its own identity, which fails
	// closed: a bot that does not know whether it was addressed must not assume
	// it was.
	Addressed bool
}

type Moderator interface {
	// DeleteMessage removes a message. reason is recorded in the platform's
	// audit log where one exists.
	DeleteMessage(ctx context.Context, ref Ref, reason string) error

	// TimeoutMember silences a member for a period. Providers MUST treat a
	// non-positive duration as a request to lift an existing timeout rather
	// than as an error, so a caller has one way to say "undo this".
	TimeoutMember(ctx context.Context, userID ID, d time.Duration, reason string) error
}

type PromptSpec struct {
	Content string
	Choices []Choice
	// Ephemeral asks that only the person who triggered it can see the result,
	// where the platform supports that. Providers that cannot MUST post
	// normally rather than fail — losing privacy is better than losing the
	// answer, and the caller cannot recover from a refusal here.
	Ephemeral bool
}

type Provider struct {
	Name   string
	Reader Reader
	Actor  Actor
}

type Reader interface {
	// Connect establishes a session and returns once it is usable.
	Connect(ctx context.Context) error

	// Messages yields inbound messages until the session ends. Implementations
	// MUST NOT emit messages from channels outside the configured allowlist,
	// and MUST NOT block the platform's read loop when the consumer is slow.
	Messages() <-chan Message

	// State reports the current connection state.
	State() ConnState

	// Close releases the session. It must be safe to call more than once, and
	// safe on a Reader that never connected.
	Close() error
}

type Ref struct {
	ChannelID ID
	MessageID ID
	ThreadID  ID
}

type ResponseToken string

type Status int