browser

Documentation

Overview

Package browser provides headless Chrome automation for form filling

Index

• Constants
• type Browser
  • func New(cfg BrowserConfig, profile *config.Profile, allowedDomains []string) (*Browser, error)
  • func (b *Browser) Close()
  • func (b *Browser) NavigateAndFill(url string, brokerID string, autoSubmit bool) (*FormResult, error)
• type BrowserConfig
  • func DefaultConfig() BrowserConfig
• type CaptchaInfo
  • func (c CaptchaInfo) GetCaptchaDescription() string
  • func (c CaptchaInfo) IsCaptchaBlocking() bool
• type ConfirmationHandler
  • func NewConfirmationHandler(brokerDomains []string) *ConfirmationHandler
  • func (h *ConfirmationHandler) ClickConfirmationLink(confirmURL string, validateDomain bool) (*ConfirmationResult, error)
  • func (h *ConfirmationHandler) ExtractConfirmationStatus(result *ConfirmationResult) string
  • func (h *ConfirmationHandler) ValidateDomain(confirmURL string) (bool, string, error)
• type ConfirmationResult
• type FieldMapping
• type FillResult
• type FormFiller
  • func NewFormFiller(profile *config.Profile) *FormFiller
  • func (f *FormFiller) Fill(ctx context.Context) *FillResult
• type FormResult

Constants

const (
	CaptchaTypeRecaptchaV2  = "recaptcha_v2"
	CaptchaTypeRecaptchaV3  = "recaptcha_v3"
	CaptchaTypeHCaptcha     = "hcaptcha"
	CaptchaTypeTurnstile    = "cloudflare_turnstile"
	CaptchaTypeFunCaptcha   = "funcaptcha"
	CaptchaTypeImageCaptcha = "image_captcha"
	CaptchaTypeTextCaptcha  = "text_captcha"
	CaptchaTypeCloudflare   = "cloudflare_challenge"
	CaptchaTypeUnknown      = "unknown"
)

CaptchaType constants

Types

type Browser

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

Browser wraps chromedp for headless Chrome automation

func New

func New(cfg BrowserConfig, profile *config.Profile, allowedDomains []string) (*Browser, error)

New creates a new Browser instance. allowedDomains restricts the hosts NavigateAndFill is willing to navigate to and autofill with profile PII (see matchesAllowedDomain); pass nil/empty to skip that check entirely (e.g. for callers that don't yet have a broker domain list).

func (*Browser) Close

func (b *Browser) Close()

Close cleans up browser resources

func (*Browser) NavigateAndFill

func (b *Browser) NavigateAndFill(url string, brokerID string, autoSubmit bool) (*FormResult, error)

NavigateAndFill navigates to a URL and attempts to fill any opt-out form

type BrowserConfig

type BrowserConfig struct {
	Headless      bool
	Timeout       time.Duration
	ScreenshotDir string
	UserAgent     string
	WindowWidth   int
	WindowHeight  int
	WaitForUser   bool         // If true, pause when CAPTCHA detected for user to solve
	WaitCallback  func() error // Called when waiting for user (e.g., to prompt in terminal)
}

BrowserConfig holds browser automation settings

func DefaultConfig

func DefaultConfig() BrowserConfig

DefaultConfig returns sensible default browser settings

type CaptchaInfo

type CaptchaInfo struct {
	Found       bool
	Type        string
	FrameSrc    string
	ElementID   string
	Confidence  float64
	Description string
}

CaptchaInfo contains information about detected CAPTCHAs

func (CaptchaInfo) GetCaptchaDescription

func (c CaptchaInfo) GetCaptchaDescription() string

GetCaptchaDescription returns a human-readable description

func (CaptchaInfo) IsCaptchaBlocking

func (c CaptchaInfo) IsCaptchaBlocking() bool

IsCaptchaBlocking returns true if the CAPTCHA requires human intervention

type ConfirmationHandler

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

ConfirmationHandler handles clicking confirmation links from emails

func NewConfirmationHandler

func NewConfirmationHandler(brokerDomains []string) *ConfirmationHandler

NewConfirmationHandler creates a new handler with known broker domains

func (*ConfirmationHandler) ClickConfirmationLink

func (h *ConfirmationHandler) ClickConfirmationLink(confirmURL string, validateDomain bool) (*ConfirmationResult, error)

ClickConfirmationLink sends a GET request to the confirmation URL

func (*ConfirmationHandler) ExtractConfirmationStatus

func (h *ConfirmationHandler) ExtractConfirmationStatus(result *ConfirmationResult) string

ExtractConfirmationStatus extracts a human-readable status from the response

func (*ConfirmationHandler) ValidateDomain

func (h *ConfirmationHandler) ValidateDomain(confirmURL string) (bool, string, error)

ValidateDomain checks if the URL belongs to a known broker domain

type ConfirmationResult

type ConfirmationResult struct {
	Success      bool
	URL          string
	FinalURL     string
	StatusCode   int
	ResponseBody string
	ErrorMessage string
	RedirectPath []string
}

ConfirmationResult holds the outcome of clicking a confirmation link

type FieldMapping

type FieldMapping struct {
	FieldType    string
	ProfileValue string
	Selectors    []string
	Patterns     []string // Patterns to match in name/id/placeholder
}

FieldMapping maps detected field types to profile values

type FillResult

type FillResult struct {
	FilledFields  []string
	MissingFields []string
	Errors        []string
}

FillResult contains the outcome of form filling

type FormFiller

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

FormFiller handles form field detection and auto-filling

func NewFormFiller

func NewFormFiller(profile *config.Profile) *FormFiller

NewFormFiller creates a new FormFiller

func (*FormFiller) Fill

func (f *FormFiller) Fill(ctx context.Context) *FillResult

Fill detects and fills form fields

type FormResult

type FormResult struct {
	Success         bool
	URL             string
	BrokerID        string
	FieldsFilled    []string
	FieldsMissing   []string
	CaptchaFound    bool
	CaptchaType     string
	ScreenshotPath  string
	ErrorMessage    string
	SubmitAttempted bool
	FillErrors      []string // real (non-"not found") errors hit while filling fields, e.g. context timeouts
}

FormResult represents the outcome of a form fill attempt