statement

type Candidate struct {
	UserID    uuid.UUID
	Timezone  string
	Email     string
	FirstName string
	// HasApp: the account has a live iPhone-app session, so the app link is left out.
	HasApp bool
	// Note is what the figures cover, when it is not the whole account (a free account's primary vehicle); the Job fills it.
	Note string
}

type Input struct {
	Period    string // YYYY-MM, the month being reported
	FirstName string
	Currency  string
	Month     ledger.Monthly
	// Prev is the previous month's statement, or nil when it could not
	// be read.
	Prev  *ledger.Monthly
	Links Links
	// Savings is the month's off-peak saving estimate, or nil. It is only ever
	// built for a user who is already getting this email.
	Savings *ledger.Savings
	// Note, when set, is a line under the heading saying what the figures cover ("Showing R1T. Pro includes all vehicles." for a free account).
	Note string
}

type Job struct {
	Store   Store
	Mailer  Mailer
	Monthly MonthlyFunc
	Savings SavingsFunc // optional
	// NoteFor, optional, says what a user's figures cover when it is not the whole account; Monthly and Savings must narrow the same way.
	NoteFor func(ctx context.Context, uid uuid.UUID) string
	Signer  *Signer
	// Enabled reports whether the operator flag covers the user.
	Enabled func(userID string) bool
	BaseURL string
	Logger  *slog.Logger
	// Now and Pause are overridable for tests. Pause is called between
	// sends (the throttle); nil uses a 500 ms sleep (2 sends/s).
	Now   func() time.Time
	Pause func(ctx context.Context)
}

type Links struct {
	Statement string
	Share     string
	Unpriced  string
	Settings  string
	// Unsubscribe is the signed one-click link (GET shows a page,
	// POST performs it).
	Unsubscribe string
	// IOSApp is the iPhone app link (RIVOLT_IOS_APP_URL); empty leaves the line out.
	IOSApp string
}

type Mailer interface {
	Send(ctx context.Context, m email.Message) error
}

type MonthlyFunc func(ctx context.Context, uid uuid.UUID, period string, loc *time.Location) (ledger.Monthly, error)

type Prefs struct {
	Enabled  bool
	Timezone string // IANA; "UTC" when unset
}

type Rendered struct {
	Subject string
	Text    string
	HTML    string
	// Silent is true when the month had no sessions and no drives:
	// nothing is sent.
	Silent bool
}

type SavingsFunc func(ctx context.Context, uid uuid.UUID, period string, loc *time.Location) (*ledger.Savings, error)

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

type Stats struct {
	Considered, Due, Sent, Failed, Skipped, AlreadyDone int
	// StuckSending is claims left 'sending' for over an hour.
	StuckSending int
}

type Store interface {
	GetPrefs(ctx context.Context, uid uuid.UUID) (Prefs, error)
	SetPrefs(ctx context.Context, uid uuid.UUID, p Prefs) error
	// LastSentPeriod is the newest period with status 'sent', or "".
	LastSentPeriod(ctx context.Context, uid uuid.UUID) (string, error)
	// Email returns the account's VERIFIED email address ("" = none or
	// unverified): statements are only ever mailed to an address the
	// identity provider verified.
	Email(ctx context.Context, uid uuid.UUID) (string, error)
	// OptedIn lists users with enabled=true and an email address.
	OptedIn(ctx context.Context) ([]Candidate, error)
	// Claim atomically reserves (user, period). It returns true for a
	// new row or a 'failed' row inside RetryWindow; a period that is
	// sending, sent or skipped (or a failed one past the window) is not
	// claimable. This is the idempotency key: it holds across replicas.
	Claim(ctx context.Context, uid uuid.UUID, period string, now time.Time) (bool, error)
	Mark(ctx context.Context, uid uuid.UUID, period, status, reason string, now time.Time) error
	// StuckSending counts claims left in 'sending' for longer than d
	// (a crash between Claim and Mark: at-most-once, never resent, so
	// this is how a silently lost month becomes visible).
	StuckSending(ctx context.Context, d time.Duration, now time.Time) (int, error)
	// Purge deletes send rows created before cutoff.
	Purge(ctx context.Context, cutoff time.Time) (int64, error)
}