source

type Action struct {
	Op   string // "none" | "seen" | "move"
	Dest string // destination mailbox/folder for "move"; empty otherwise
}

type Claimed struct {
	SourceID     string
	Tenant       string // slug
	Stack        string
	Pack         string
	DeclaredID   string
	Kind         string
	Config       json.RawMessage
	Cursor       Cursor // nil when never polled
	EverySeconds int
}

type Conn interface {
	// Poll reads items strictly after cur, up to limit, in ascending order.
	// Each returned Item carries the cursor to persist once that item's run
	// and ack both succeed. `drained` is the cursor to persist only if the
	// WHOLE batch is processed without a failure (or the batch is empty): it
	// carries side-band progress such as an IMAP UIDVALIDITY reset, so an
	// empty or renumbered source is not rescanned forever. drained may be nil.
	Poll(ctx context.Context, cur Cursor, limit int) (items []Item, drained Cursor, err error)

	// Ack applies act to one item at the source. Called by the poller only
	// after that item's run reached a successful terminal. A "none" action
	// is a no-op. An error stops the batch (the cursor does not advance past
	// this item), so Ack must be safe to retry on the next poll.
	Ack(ctx context.Context, it Item, act Action) error

	// Close releases the connection. Always called once per successful Open.
	Close() error
}

type Cursor json.RawMessage

type Declared struct {
	Tenant       string // slug
	Stack        string
	Pack         string
	DeclaredID   string
	Kind         string
	Config       json.RawMessage // the pack line, verbatim
	Enabled      bool
	EverySeconds int
	Version      int64
}

type Item struct {
	// Key is a stable dedup identity for this item within its source,
	// surfaced to the stack as `_txc.source.key` so a run can guard against
	// an at-least-once redelivery (kv/cas, or txco://imap/append object_key).
	// For IMAP it is "<uidvalidity>:<uid>".
	Key string

	// Raw is the item's bytes — RFC 5322 for an IMAP message. The poller
	// hands these to a kind-neutral parser (chassis/mail.ParseMessage for
	// mail) so a fetched message and an LMTP-delivered one produce identical
	// envelope JSON.
	Raw []byte

	// Meta is kind-specific facts the poller stamps under `_txc.source.*`
	// verbatim (it never interprets them) — e.g. `{"uid":42,"flags":[...]}`.
	Meta json.RawMessage

	// Cursor is the cursor to persist AFTER this item's run and ack both
	// succeed. Items arrive in order; the poller advances the stored cursor
	// item-by-item on success and stops at the first failure, so a mid-batch
	// failure never skips an unprocessed item.
	Cursor Cursor
}

type Kind interface {
	// Name is the kind identity used in a source's `kind` field ("imap").
	Name() string
	// Open dials and authenticates one connection. See OpenParams for the
	// credential lifetime contract.
	Open(ctx context.Context, p OpenParams) (Conn, error)
}

type OpenParams struct {
	// Config is the kind-specific declared config blob (the pack line's
	// fields), e.g. `{"host":"imap.fastmail.com","port":993,...}`. It never
	// contains the secret VALUE — only its name, resolved by the poller.
	Config json.RawMessage

	// Cred is the materialized secret value (the mailbox password). It is
	// zeroed by the caller the moment Open returns; do not retain it.
	Cred []byte

	// Guard is the egress policy for the outbound dial. When non-nil a Kind
	// MUST route its connection through it (net.Dialer.Control =
	// egress.DialControl(guard)) so a source cannot be pointed at loopback,
	// link-local, or private address space. A nil Guard means "no policy"
	// (dev/test).
	Guard egress.Guard

	// Logger is the poller's logger, scoped for this source.
	Logger *zap.Logger
}

type Status struct {
	SourceID   string `json:"source_id"`
	Stack      string `json:"stack"`
	Pack       string `json:"pack"`
	DeclaredID string `json:"declared_id"`
	Kind       string `json:"kind"`
	Enabled    bool   `json:"enabled"`
	Retired    bool   `json:"retired"`
	Status     string `json:"status"`
	ClaimedBy  string `json:"claimed_by,omitempty"`
	Cursor     string `json:"cursor,omitempty"`
	NextPollAt string `json:"next_poll_at,omitempty"`
	LastPollAt string `json:"last_poll_at,omitempty"`
	LastError  string `json:"last_error,omitempty"`
	Attempts   int    `json:"attempts"`
}

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