gopilot

type BoundingRect struct {
	// Top is the distance from the top of the viewport to the top of the element.
	Top float64 `json:"top"`
	// Left is the distance from the left of the viewport to the left of the element.
	Left float64 `json:"left"`
	// Bottom is the distance from the top of the viewport to the bottom of the element.
	Bottom float64 `json:"bottom"`
	// Right is the distance from the left of the viewport to the right of the element.
	Right float64 `json:"right"`
	// X is the horizontal coordinate of the element.
	X float64 `json:"x"`
	// Y is the vertical coordinate of the element.
	Y float64 `json:"y"`
	// Width is the width of the element.
	Width float64 `json:"width"`
	// Height is the height of the element.
	Height float64 `json:"height"`
	// CenterX is the centered position on x-axis
	CenterX float64
	// CenterY is the centered position on y-axis
	CenterY float64
}

type Browser interface {
	// Open initiates a new browser session.
	// It takes a context and BrowserOpenInput as parameters.
	// Returns an error if the browser fails to start.
	Open(ctx context.Context, in *BrowserOpenInput) error

	// NewPage creates a new page or tab in the browser.
	// Accepts context and BrowserNewPageInput to specify creation parameters.
	// Returns a BrowserNewPageOutput containing the newly created page
	// or an error if the page cannot be created.
	NewPage(ctx context.Context, in *BrowserNewPageInput) (*BrowserNewPageOutput, error)

	// GetPages retrieves only pages created by this session (tracked pages).
	// These are pages created with NewTab: true. Calling Close() on these pages will close them.
	// Returns a BrowserGetPagesOutput with a list of session pages or an error if retrieving fails.
	GetPages(ctx context.Context, in *BrowserGetPagesInput) (*BrowserGetPagesOutput, error)

	// GetAllPages retrieves ALL pages in the browser, including non-session pages.
	// Pages returned are NOT session-tracked, and calling Close() on them is a no-op.
	// Use this for inspection/debugging. For pages created by this session, use GetPages().
	GetAllPages(ctx context.Context, in *BrowserGetPagesInput) (*BrowserGetPagesOutput, error)

	// Close shuts down the browser instance and cleans up any resources.
	// Only closes session pages (pages created by this instance with NewTab: true).
	// For external browsers, closes session pages but leaves the browser running.
	Close(ctx context.Context) error

	// GetDevToolClient retrieves the DevTools client associated with the browser.
	// This client allows for advanced interactions with the browser's DevTools protocol,
	// enabling custom actions and low-level debugging or profiling features.
	GetDevToolClient() *devtool.DevTools
}

type BrowserConfig struct {
	// Path specifies the path to the browser executable.
	Path string

	// DebugPort specifies the port for debugging connections.
	DebugPort string

	// Args contains additional command-line arguments to pass when launching the browser.
	Args []string

	// Envs holds any environment variables to set for the browser process.
	Envs []string

	// OpenTimeout defines how long to wait for Chrome to print the "DevTools listening on" message during startup.
	// If nil, a default of 5 seconds is used. Increase this if your environment starts Chrome slowly.
	OpenTimeout *time.Duration

	// CloseTimeout defines how long to wait for the Chrome process to terminate during shutdown.
	// If nil, a default of 5 seconds is used. Increase this if your environment needs more time to exit cleanly.
	CloseTimeout *time.Duration

	// ConnectionURL specifies the URL of an existing Chrome/Chromium browser to connect to.
	// When set, gopilot will connect to the existing browser instead of launching a new process.
	// Supports both WebSocket URLs (ws://127.0.0.1:9222/devtools/browser/UUID) and HTTP (http://127.0.0.1:9222).
	// The external browser will NOT be closed when Browser.Close() is called.
	//
	// Example:
	//   cfg := gopilot.NewBrowserConfig()
	//   cfg.ConnectionURL = "http://127.0.0.1:9222"
	ConnectionURL string
}

type BrowserGetPagesInput struct{}

type BrowserGetPagesOutput struct {
	Pages []Page
}

type BrowserNewPageInput struct {
	NewTab bool
	URL    string
}

type BrowserNewPageOutput struct {
	Page Page
}

type BrowserOpenInput struct{}

type ClearLocalStorageInput struct{}

type ClearLocalStorageOutput struct{}

type DispatchEventType string

type Element interface {
	ElementInput
	ElementDOM

	// TakeScreenshot captures a screenshot of the element.
	// It uses the element's position and size to define the capture area.
	// Input parameters can specify the format of the image.
	// Returns the screenshot data as bytes or an error if the capture fails.
	TakeScreenshot(ctx context.Context, in *ElementTakeScreenshotInput) (*ElementTakeScreenshotOutput, error)

	// GetNodeID gives the current node of the element
	GetNodeID(ctx context.Context) dom.NodeID
}

type ElementClickInput struct {
	StepDuration time.Duration // Duration for each step of the click action.
	HoldDuration time.Duration // Duration to hold the mouse press before releasing.

	ReturnHoldRelease bool // Return a release function to let user decide when to release mouse press
}

type ElementClickOutput struct {
	X float64 `json:"x"` // X coordinate of the click position.
	Y float64 `json:"y"` // Y coordinate of the click position.

	Release func() error
}

type ElementDOM interface {
	// HTML retrieves the element's outer HTML content
	HTML(ctx context.Context) (string, error)

	// Text retrieves the element's text content.
	Text(ctx context.Context) (string, error)

	// Focus sets focus on the element, allowing it to receive input.
	// Returns an error if the action fails.
	Focus(ctx context.Context) error

	// ScrollIntoView performs an action to scroll the element into the viewport.
	// Accepts an ElementScrollIntoViewInput with scroll parameters.
	// Returns an ElementScrollIntoViewOutput or an error if the action fails.
	ScrollIntoView(ctx context.Context, in *ElementScrollIntoViewInput) (*ElementScrollIntoViewOutput, error)

	// GetRect retrieves the bounding rectangle of the element.
	// Returns a BoundingRect containing the dimensions and position of the element, or an error if retrieval fails.
	GetRect(ctx context.Context) (*BoundingRect, error)

	// Remove the element from the DOM tree
	Remove(ctx context.Context) error
}

type ElementInput interface {
	// Click simulates a mouse click on the element.
	// Accepts an ElementClickInput containing details for the click action.
	// Returns an ElementClickOutput with the result or an error if the click fails.
	Click(ctx context.Context, in *ElementClickInput) (*ElementClickOutput, error)
}

type ElementScrollIntoViewInput struct{}

type ElementScrollIntoViewOutput struct {
	// X is the X coordinate of the scroll-to view position.
	X float64 `json:"x"`

	// Y is the Y coordinate of the scroll-to view position.
	Y float64 `json:"y"`
}

type ElementTakeScreenshotInput struct {
	// Format specifies the desired image format for the screenshot.
	// Common formats include "png" and "jpeg".
	Format string
}

type ElementTakeScreenshotOutput struct {
	// Data contains the base64 encoded screenshot image data.
	Data []byte
}

type GetCookiesInput struct{}

type GetCookiesOutput struct {
	Cookies []PageCookie // List of cookies.
}

type GetLocalStorageInput struct{}

type GetLocalStorageOutput struct {
	Items []LocalStorageItem
}

type InterceptRequestCallback func(ctx context.Context, req *fetch.RequestPausedReply, continueArgs *fetch.ContinueRequestArgs) (*fetch.FulfillRequestArgs, error)

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

type InterceptResponseCallback func(ctx context.Context, req *fetch.RequestPausedReply, continueArgs *fetch.ContinueResponseArgs) error

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

type LocalStorageItem struct {
	Name  string `json:"name"`
	Value string `json:"value,omitempty"`
}

type Page interface {
	PageNavigation
	PageDOM
	PageFetch
	PageStorage
	PageInput

	// Close closes the page.
	// Returns an error if closing the page fails.
	Close(ctx context.Context) error

	// Evaluate runs JavaScript on the page.
	// Takes a PageEvaluateInput and returns a PageEvaluateOutput or an error.
	Evaluate(ctx context.Context, in *PageEvaluateInput) (*PageEvaluateOutput, error)

	// TakeScreenshot captures a screenshot of the page.
	// You can choose to capture the entire page or just the visible viewport.
	// Input parameters allow you to specify the image format and capture area.
	// Returns the screenshot data or an error if the capture fails.
	TakeScreenshot(ctx context.Context, in *PageTakeScreenshotInput) (*PageTakeScreenshotOutput, error)

	// GetTargetID returns the unique identifier for the page's target.
	// This ID can be used to distinguish different pages or targets in the browser.
	GetTargetID() string

	// GetCDPClient retrieves the Chrome DevTools Protocol (CDP) client associated with the page.
	// The CDP client allows for direct communication with the browser's protocol.
	// This is useful for performing low-level operations and custom actions not exposed by higher-level methods.
	GetCDPClient() *cdp.Client
}

type PageCookie struct {
	Name     string     // The name of the cookie.
	Value    string     // The value of the cookie.
	Domain   string     // The domain the cookie is associated with.
	Path     string     // The path the cookie is accessible from.
	Size     int        // The size of the cookie in bytes.
	Expires  *time.Time // The expiration time of the cookie.
	Secure   bool       // Indicates if the cookie is secure (only sent over HTTPS).
	HttpOnly bool       // Indicates if the cookie is accessible via HTTP only (not accessible via JavaScript).
	Session  bool       // Indicates if the cookie is a session cookie.
}

type PageDOM interface {
	// GetContent retrieves the HTML content of the page as a string.
	// Returns the content or an error if retrieving fails.
	GetContent(ctx context.Context) (string, error)

	// SetContent replaces the current DOM with supplied content
	SetContent(ctx context.Context, content string) error

	// QuerySelector finds an element matching the selector.
	// Takes a PageQuerySelectorInput and returns a PageQuerySelectorOutput or an error.
	QuerySelector(ctx context.Context, in *PageQuerySelectorInput) (*PageQuerySelectorOutput, error)

	// Search finds an element matching the text, query selector or xpath
	// Takes a PageSearchInput and returns a PageSearchOutput or an error.
	Search(ctx context.Context, in *PageSearchInput) (*PageSearchOutput, error)
}

type PageEvaluateInput struct {
	AwaitPromise bool
	ReturnValue  bool
	Expression   string
}

type PageEvaluateOutput struct {
	Value json.RawMessage
}

type PageFetch interface {
	// EnableFetch enables network fetch interception.
	// Returns an error if enabling fails.
	EnableFetch(ctx context.Context) error

	// DisableFetch disables network fetch interception.
	// Returns an error if disabling fails.
	DisableFetch(ctx context.Context) error

	// AddInterceptRequest adds a request interception callback.
	// Returns a handle that can be used to remove the callback later.
	AddInterceptRequest(ctx context.Context, cb InterceptRequestCallback) *InterceptRequestHandle

	// RemoveInterceptRequest removes a request interception callback.
	// The handle parameter should be the value returned by AddInterceptRequest.
	RemoveInterceptRequest(ctx context.Context, handle *InterceptRequestHandle)

	// AddInterceptResponse adds a response interception callback.
	// Returns a handle that can be used to remove the callback later.
	AddInterceptResponse(ctx context.Context, cb InterceptResponseCallback) *InterceptResponseHandle

	// RemoveInterceptResponse removes a response interception callback.
	// The handle parameter should be the value returned by AddInterceptResponse.
	RemoveInterceptResponse(ctx context.Context, handle *InterceptResponseHandle)
}

type PageInput interface {
	// TypeText sends a sequence of keystrokes to the element as if typed by a user.
	// Accepts an ElementTypeInput containing the text to type.
	// Returns an ElementTypeOutput with the result or an error if typing fails.
	TypeText(ctx context.Context, in *PageTypeTextInput) (*PageTypeTextOutput, error)
}

type PageNavigateInput struct {
	URL                string // The URL to navigate to.
	WaitDomContentLoad bool   // If true, waits for the DOM content to load before returning.
}

type PageNavigateOutput struct {
	LoaderID network.LoaderID // The LoaderID associated with the navigation.
}

type PageNavigation interface {
	// Activate brings page to front
	Activate(ctx context.Context) error

	// Navigate navigates the page to the specified URL.
	// The input is a PageNavigateInput containing the URL to navigate to.
	// It returns a PageNavigateOutput or an error if the navigation fails.
	Navigate(ctx context.Context, in *PageNavigateInput) (*PageNavigateOutput, error)

	// Reload reloads the current page.
	// It can take a PageReloadInput and returns a PageReloadOutput or an error.
	Reload(ctx context.Context, in *PageReloadInput) (*PageReloadOutput, error)
}

type PageQuerySelectorInput struct {
	Selector string
}

type PageQuerySelectorOutput struct {
	Element Element
}

type PageReloadInput struct {
	LoaderID           network.LoaderID // The LoaderID of the previous load.
	WaitDomContentLoad bool             // If true, waits for the DOM content to load after reload.
}

type PageReloadOutput struct{}

type PageSearchInput struct {
	Selector     string        // selector for querying the element.
	Pierce       bool          // Include User Agent Shadow DOM if true.
	WaitDuration time.Duration // Max duration to wait for an element to be present.
	TickDuration time.Duration // Duration between search attempts; defaults to 1 second if unset.
}

type PageSearchOutput struct {
	Element Element // The first element matching the query.
}

type PageStorage interface {
	// GetCookies retrieves cookies for the current page.
	// Takes a GetCookiesInput and returns GetCookiesOutput or an error.
	GetCookies(ctx context.Context, in *GetCookiesInput) (*GetCookiesOutput, error)

	// SetCookies sets cookies for the current page.
	// Takes a SetCookiesInput and returns SetCookiesOutput or an error.
	SetCookies(ctx context.Context, in *SetCookiesInput) (*SetCookiesOutput, error)

	// ClearCookies clears cookies for the current page.
	ClearCookies(ctx context.Context) error

	GetLocalStorage(ctx context.Context, in *GetLocalStorageInput) (*GetLocalStorageOutput, error)
	SetLocalStorage(ctx context.Context, in *SetLocalStorageInput) (*SetLocalStorageOutput, error)
	ClearLocalStorage(ctx context.Context) error
}

type PageTakeScreenshotInput struct {
	// Format specifies the desired image format for the screenshot.
	// Options could be "png" or "jpeg".
	Format string

	// Full determines whether to capture the entire page or only the current viewport.
	Full bool

	// Viewport allows specifying a custom area of the page to capture.
	Viewport *cdppage.Viewport
}

type PageTakeScreenshotOutput struct {
	// Data contains the screenshot image data.
	Data []byte
}

type PageTypeTextInput struct {
	Text      string        // The text to be typed into the page.
	Delay     time.Duration // (optional) Duration between keystrokes.
	DelayFunc TypeDelayFunc // (optional) Custom function for typing delays.

	UseRawKeyDown bool
}

type PageTypeTextOutput struct{}

type SetCookiesInput struct {
	Cookies []PageCookie // List of cookies to set.
}

type SetCookiesOutput struct{}

type SetLocalStorageInput struct {
	Items []LocalStorageItem
}

type SetLocalStorageOutput struct{}

type TypeDelayFunc func() time.Duration

type XHREvent struct {
	URL    string `json:"url"`    // The URL that was requested
	Body   string `json:"body"`   // The body of the response
	Base64 bool   `json:"base64"` // Indicates if the response body is Base64 encoded
	Error  error  `json:"-"`      // Error encountered during the request (if any)
}

type XHRMonitor interface {
	// Listen starts listening for XHR events that match the provided patterns.
	// It returns a channel of XHREvent and an error if the operation fails.
	Listen(ctx context.Context, patterns []string) (chan *XHREvent, error)

	// Stop stops monitoring the XHR requests.
	// Returns an error if stopping fails.
	Stop(ctx context.Context) error
}