package sdk

import "context"

// Channel registers a chat platform adapter (QQ, WeChat, Telegram, ...).
//
// The SDK pins only the lifecycle shape. The authoritative contract for
// adapters lives in internal/channel/adapter (design authority
// DevDocs/design/08-渠道接入.md §1, the PlatformAdapter contract) and is
// implemented in milestone M6. This interface mirrors the lifecycle portion of
// that contract — Name/Connect/Disconnect/IsConnected/HealthCheck — without
// depending on the internal message model, so a platform plugin can register
// itself here while the message flow is provided by the channel layer.
//
// Implementations must be safe for concurrent use.
type Channel interface {
	// Name returns the platform identifier (for example "qq", "telegram").
	Name() string
	// Connect establishes the platform connection. It may be called more than
	// once and must be idempotent.
	Connect(ctx context.Context) error
	// Disconnect tears the connection down gracefully. It returns nil when the
	// adapter was already disconnected.
	Disconnect(ctx context.Context) error
	// IsConnected reports whether the connection is currently up.
	IsConnected() bool
	// HealthCheck probes the platform and returns an error when it is unhealthy.
	HealthCheck(ctx context.Context) error
}