dm

type Client interface {
	Dial(appnet.Addr) (net.Conn, error)
	Listen(appnet.Type, routing.Port) (net.Listener, error)
}

type Config struct {
	// Client is the transport (dial/listen). Required.
	Client Client
	// Store persists messages (nil = ephemeral; delivery is never blocked).
	Store history.Store
	// Networks the controller listens + sends on (e.g. dmsg, skynet).
	Networks []appnet.Type
	// Port the controller listens on / dials. Zero = the well-known chat port (1).
	Port routing.Port
	// OnEvent is called for every surfaced message (inbound + outbound mirror).
	// Never nil in practice; a nil callback simply drops surfacing.
	OnEvent func(Event)
	// OnReceipt is called for an inbound receipt about a message WE sent: a
	// chat-ack (the peer's app received it) or a chat-read (the peer actually
	// displayed it). id is the envelope id of the original message, so a UI can
	// advance that bubble's delivery status; peer is who the receipt came from.
	// Receipts are consumed here — they are never surfaced as chat lines.
	// Nil = the app doesn't track delivery status.
	OnReceipt func(peer, id, kind string)
	// OnDelete is called for an inbound chat-delete: the peer asks us to drop
	// (tombstone) a message THEY sent us, identified by its envelope id. Like a
	// receipt it is consumed here, never surfaced as a chat line; the app
	// replaces the message with a "deleted" placeholder. Nil = deletes ignored.
	OnDelete func(peer, id string)
	// StaleAckWindow bounds how long a RequestAck send waits for the peer's
	// chat-ack before concluding the cached conn is half-open and evicting it,
	// so the next send redials. A live peer acks in well under a second; this
	// is generous so a momentarily-slow peer doesn't cost a healthy conn.
	// Zero disables the check.
	StaleAckWindow time.Duration
	// DialRetry, if set, wraps each dial attempt (e.g. a netutil.Retrier's Do)
	// to preserve the native app's retry behavior. Nil = single attempt.
	DialRetry func(context.Context, func() error) error
	// PreHandleFrame, if set, is offered every inbound frame before chat
	// decoding; returning true consumes the frame (used by the native app for
	// its pair-control envelopes). Nil = no interception.
	PreHandleFrame func(peer cipher.PubKey, payload []byte) bool
	// RawText sends a plain (no-reply, no-ack) message as bare text instead of
	// a chat-msg envelope with a minted id. Off by default: every message then
	// carries a stable id, which is what quoted replies, read ticks and
	// delete-for-everyone key on, natively and in the wasm visor alike. Set it
	// only to keep a default send byte-identical on the wire for pre-envelope
	// peers; inbound bare text is always accepted regardless.
	RawText bool
	// Log is an optional structured logger sink.
	Log func(format string, args ...interface{})
}

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

type Event struct {
	ID      string    // message envelope id ("" for a plain, pre-envelope message)
	Dir     string    // "in" | "out"
	Peer    string    // the OTHER end's PK hex (sender for in, recipient for out)
	Network string    // "dmsg" | "skynet" | ...
	Text    string    // message body
	ReplyTo string    // quoted-reply target id ("" if not a reply)
	TS      time.Time // receive (in) or send (out) time, UTC
}

type SendOpts struct {
	// ReplyTo, when set, quotes the message with this id (threaded reply).
	ReplyTo string
	// WaitAck > 0 requests a peer-receipt ack: the message rides a chat-msg
	// envelope with ack=true and Send blocks up to WaitAck for the peer's
	// chat-ack. Zero = fire-and-forget (default).
	WaitAck time.Duration
	// RequestAck asks the peer for a chat-ack WITHOUT blocking: the message
	// rides an id'd envelope with ack=true exactly like WaitAck, but Send
	// returns as soon as the write lands and the ack surfaces later through
	// OnReceipt. This is the message-status lifecycle a UI wants (sent →
	// received → read) as opposed to a CLI's synchronous --wait. Ignored when
	// WaitAck is set, which already asks for the ack and waits for it.
	RequestAck bool
	// Auto picks the network automatically instead of using the netType arg:
	// reuse a warm conn if one exists (so replies also follow the peer's chosen
	// path), else send over dmsg immediately — no route setup, instant first
	// contact — and warm a skynet route in the background so subsequent messages
	// upgrade to the faster/steadier routed transport. netType is ignored.
	Auto bool
}

type SendResult struct {
	ID      string        // the envelope id assigned to this message ("" for a plain send)
	Acked   bool          // true if a WaitAck send received its ack in time
	Elapsed time.Duration // time from write to ack (only meaningful when Acked)
	Network appnet.Type   // the network the message actually went out on (may differ via fallback)
}

type Stats struct {
	InboundMsgs    int64
	OutboundMsgs   int64
	InboundDrops   int64 // conn read errors (peer/transport dropped)
	OutboundFails  int64 // sends that failed even after retry + fallback
	OutboundRetry  int64 // stale-cached-conn writes rescued by a redial+retry
	OutboundFallbk int64 // sends rescued by the alternate network
	LastRxAt       time.Time
	LastTxAt       time.Time
}