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"
)

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 // one of the CaptchaType constants
}

CaptchaInfo is the result of detectCaptcha.

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. reCAPTCHA v3 is invisible and usually doesn't.

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