gmail

Documentation

Overview

Package gmail implements a Reader that extracts transactions from Gmail.

Package gmail provides the Gmail reader and its plugin integration.

Index

• func Provider(guideData []byte) plugins.Provider
• type Config
• type Plugin
  • func (p *Plugin) Metadata() plugins.ProviderMetadata
  • func (p *Plugin) NewEmailSearcher(input plugins.ProviderInput) (api.EmailSearcher, error)
  • func (p *Plugin) NewReader(input plugins.ProviderInput) (api.Reader, error)
  • func (p *Plugin) SetGuideData(data []byte)
• type Reader
  • func New(httpClient *http.Client, cfg Config, logger *slog.Logger) (*Reader, error)
  • func (r *Reader) Read(ctx context.Context, out chan<- *api.TransactionDetails, ackChan <-chan string) error
  • func (r *Reader) Search(ctx context.Context, query api.EmailSearchQuery) ([]api.EmailSearchResult, error)

Functions

func Provider

func Provider(guideData []byte) plugins.Provider

Provider returns the Gmail provider registration.

Types

type Config

type Config struct {
	// Rules defines the email matching rules for transaction extraction.
	Rules []api.Rule
	// Resolver maps merchant info to category and bucket.
	Resolver api.CategoryResolver
	// Interval between rule evaluations. Defaults to 60 seconds.
	Interval time.Duration
	// LookbackDays limits how far back in time to search for emails.
	// Defaults to 180 days (6 months). Set to 0 to use the default.
	LookbackDays int
	// LastScanAt is the timestamp of the last successful scan. When set
	// (and ForceFullScan is false) only emails received after this time
	// are fetched, avoiding a full lookback scan every interval.
	LastScanAt *time.Time
	// ForceFullScan bypasses LastScanAt and fetches the full lookback window.
	// Used for force-rescan and retroactive rule application.
	ForceFullScan bool
	// RunOnce returns after the first scan iteration.
	RunOnce bool
	// OnCheckpoint is called with time.Now() after each successful scan iteration.
	// Use it to persist the checkpoint so the next run starts from here.
	OnCheckpoint func(time.Time)
	// State is the state manager for tracking processed messages.
	State *state.Manager
	// DiagnosticSink records best-effort extraction diagnostics.
	DiagnosticSink api.DiagnosticSink
	// ObservabilityScope records reader telemetry. Defaults to a Gmail reader scope.
	ObservabilityScope *observability.Scope
}

Config holds configuration for the Gmail reader.

type Plugin

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

Plugin builds Gmail provider capabilities.

func (*Plugin) Metadata

func (p *Plugin) Metadata() plugins.ProviderMetadata

Metadata returns catalog metadata for the Gmail provider.

func (*Plugin) NewEmailSearcher

func (p *Plugin) NewEmailSearcher(input plugins.ProviderInput) (api.EmailSearcher, error)

NewEmailSearcher creates a new Gmail email searcher instance.

func (*Plugin) NewReader

func (p *Plugin) NewReader(input plugins.ProviderInput) (api.Reader, error)

NewReader creates a new Gmail reader instance.

func (*Plugin) SetGuideData

func (p *Plugin) SetGuideData(data []byte)

SetGuideData injects the setup guide content. Application composition calls it after loading backend/internal/catalog/content/readers/gmail/guide.json via go:embed.

type Reader

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

Reader reads transactions from Gmail messages.

func New

func New(httpClient *http.Client, cfg Config, logger *slog.Logger) (*Reader, error)

New creates a new Gmail reader.

func (*Reader) Read

func (r *Reader) Read(ctx context.Context, out chan<- *api.TransactionDetails, ackChan <-chan string) error

Read continuously evaluates rules and sends extracted transactions to the output channel. It runs until the context is canceled. Messages are marked as processed only after receiving acknowledgment via ackChan.

func (*Reader) Search

func (r *Reader) Search(ctx context.Context, query api.EmailSearchQuery) ([]api.EmailSearchResult, error)

Search returns Gmail messages whose subject contains the requested text.