schema

type Action struct {
	Name string `json:"name"`
	// Purpose is the user-voice one-liner the registry projects onto
	// the public card. Names what the action lets a caller do in a
	// sentence anyone (not just an engineer) could understand. Missing
	// purpose → action doesn't appear on the catalog card (by design —
	// the validator refuses to fabricate one from the paywalled
	// description). Example: "Save a tweet to the authenticated user's
	// drafts. Private — only visible to the signed-in account."
	Purpose     string            `json:"purpose,omitempty"`
	Description string            `json:"description,omitempty"`
	Kind        string            `json:"kind"`
	Transport   string            `json:"transport"`
	Method      string            `json:"method,omitempty"`
	URLTemplate string            `json:"url_template"`
	Headers     map[string]string `json:"headers,omitempty"`
	Params      []ActionParam     `json:"params,omitempty"`
	// BodyTemplate, if non-empty, is used verbatim as the request body
	// after {{var}} substitution. Substituted values are JSON-escaped so
	// user input can't break out of the surrounding JSON string. When
	// empty, the runner synthesizes a body by JSON-marshaling every
	// Param with in="body" — useful for flat APIs, but most real-world
	// endpoints need an explicit template.
	BodyTemplate string             `json:"body_template,omitempty"`
	Result       *ActionResult      `json:"result,omitempty"`
	Requirements ActionRequirements `json:"requirements,omitempty"`
	Confidence   float64            `json:"confidence,omitempty"`
	Source       string             `json:"source,omitempty"`
}

type ActionParam struct {
	Name        string `json:"name"`
	In          string `json:"in"` // path, query, body, form, url
	Type        string `json:"type,omitempty"`
	Required    bool   `json:"required"`
	Default     string `json:"default,omitempty"`
	Description string `json:"description,omitempty"`
}

type ActionRequirements struct {
	Auth    string `json:"auth,omitempty"`
	Session string `json:"session,omitempty"`
	JS      string `json:"js,omitempty"`
}

type ActionResult struct {
	EntityType     string          `json:"entity_type,omitempty"`
	Fields         []string        `json:"fields,omitempty"`
	ResponseSchema *ResponseSchema `json:"response_schema,omitempty"`
}

type BodyTemplate struct {
	ContentType string `json:"content_type"`
	Template    string `json:"template"`
}

type Endpoint struct {
	Name string `json:"name"`
	// Purpose is the user-voice one-liner that surfaces on the public
	// catalog card. Describes what data a caller can get from this
	// endpoint in a sentence anyone (not just an engineer) understands.
	// The technical how-to — selectors, parse paths, script-tag ids —
	// goes in Description, which stays paywalled inside the full
	// package. Missing purpose → endpoint is omitted from the public
	// card (the validator will not invent one from Description).
	Purpose         string            `json:"purpose,omitempty"`
	Description     string            `json:"description,omitempty"`
	Method          string            `json:"method"`
	URLTemplate     string            `json:"url_template"`
	Headers         map[string]string `json:"headers"`
	QueryParams     []Param           `json:"query_params,omitempty"`
	Body            *BodyTemplate     `json:"body,omitempty"`
	Variables       []Variable        `json:"variables"`
	IsPrimary       bool              `json:"is_primary"`
	Confidence      float64           `json:"confidence,omitempty"`
	ResponseMapping map[string]string `json:"response_mapping,omitempty"`
	ResponseSchema  *ResponseSchema   `json:"response_schema,omitempty"`
}

type EntityField struct {
	Name       string        `json:"name"`
	Selector   string        `json:"selector"`
	Selectors  []string      `json:"selectors,omitempty"`   // ordered fallback selectors
	Attribute  string        `json:"attribute,omitempty"`   // empty = text content
	Type       string        `json:"type"`                  // "string", "number", "list"
	Required   bool          `json:"required,omitempty"`    // triggers re-discovery if empty
	ItemFields []EntityField `json:"item_fields,omitempty"` // for list items
}

type ExtractionField struct {
	Name      string `json:"name"`
	Selector  string `json:"selector"`
	Attribute string `json:"attribute,omitempty"` // empty = text content
}

type ExtractionRules struct {
	Strategy        string            `json:"strategy,omitempty"` // "css_selector" (default) or "table_rows"
	PageType        string            `json:"page_type"`          // "article", "profile", "product", "listing", "documentation", "generic"
	ContentSelector string            `json:"content_selector"`
	TitleSelector   string            `json:"title_selector,omitempty"`
	AuthorSelector  string            `json:"author_selector,omitempty"`
	DateSelector    string            `json:"date_selector,omitempty"`
	IgnoreSelectors []string          `json:"ignore_selectors,omitempty"`
	Fields          []ExtractionField `json:"fields,omitempty"`
	EntityFields    []EntityField     `json:"entity_fields,omitempty"`   // for css_selector strategy
	TableRows       *TableRowsConfig  `json:"table_rows,omitempty"`      // for table_rows strategy
	NextDataPaths   map[string]string `json:"next_data_paths,omitempty"` // named jq-style paths into __NEXT_DATA__ pageProps
}

type FieldSchema struct {
	Name   string        `json:"name"`
	Type   string        `json:"type"`             // "string", "number", "boolean", "object", "array", "null"
	Fields []FieldSchema `json:"fields,omitempty"` // for nested objects
	Items  *FieldSchema  `json:"items,omitempty"`  // for arrays: schema of each element
}

type Param struct {
	Key      string `json:"key"`
	Value    string `json:"value"`
	Required bool   `json:"required"`
}

type ResponseSchema struct {
	Type   string        `json:"type"`             // "object", "array", "string", "number", "boolean"
	Fields []FieldSchema `json:"fields,omitempty"` // for object type
	Items  *FieldSchema  `json:"items,omitempty"`  // for array type: schema of each element
}

type Runtime struct {
	// BootstrapJS is source code defining a global `bootstrap(input)`
	// function. Runs when the session's cached state is missing or past
	// BootstrapTTLSeconds. Must return an object whose values are all
	// strings — every key becomes a field on the signer's State map.
	BootstrapJS string `json:"bootstrap_js,omitempty"`

	// SignerJS is source code defining a global `sign(input)` function.
	// Runs before each outgoing request. Returns `{url, headers}`: url
	// may be the input URL with extra query parameters appended (e.g.
	// TikTok's X-Bogus); headers are merged onto the request, overriding
	// same-named existing values.
	SignerJS string `json:"signer_js,omitempty"`

	// AllowedHosts restricts hermai.fetch inside BootstrapJS. Exact
	// hostname match, case-insensitive. Required when BootstrapJS calls
	// fetch — an empty list blocks every outbound call.
	AllowedHosts []string `json:"allowed_hosts,omitempty"`

	// BootstrapTTLSeconds is how long bootstrap state stays valid
	// before re-running. Zero means use the CLI default (3600 = 1h).
	// Schemas for sites with aggressive key rotation (TikTok's msToken)
	// should set this low; X is comfortable with an hour.
	BootstrapTTLSeconds int `json:"bootstrap_ttl_seconds,omitempty"`
}

type Schema struct {
	ID string `json:"id"`
	// Site is the canonical domain key the registry validator reads.
	// Set this on every new schema. Domain is retained for backward
	// compatibility with pre-2026-04 schemas that used it as the site
	// key, but any new code should populate Site. The hermai-api
	// validator accepts either and normalizes to Site.
	Site            string           `json:"site,omitempty"`
	Domain          string           `json:"domain,omitempty"`
	URLPattern      string           `json:"url_pattern"`
	SchemaType      string           `json:"schema_type,omitempty"` // "api" or "css_selector"
	Coverage        string           `json:"coverage,omitempty"`    // partial or complete
	Version         int              `json:"version"`
	CreatedAt       time.Time        `json:"created_at"`
	DiscoveredFrom  string           `json:"discovered_from"`
	Endpoints       []Endpoint       `json:"endpoints"`
	Actions         []Action         `json:"actions,omitempty"`
	ExtractionRules *ExtractionRules `json:"extraction_rules,omitempty"`
	Session         *SessionConfig   `json:"session,omitempty"`
	Runtime         *Runtime         `json:"runtime,omitempty"`
	RequiresStealth bool             `json:"requires_stealth,omitempty"`
}

type SessionConfig struct {
	// BootstrapURL is hit before data fetches to obtain session cookies/tokens.
	BootstrapURL    string `json:"bootstrap_url"`
	BootstrapMethod string `json:"bootstrap_method"` // GET or POST
	// CaptureHeaders lists response headers to extract and forward (e.g. X-CSRF-Token).
	CaptureHeaders []string `json:"capture_headers,omitempty"`
	// CaptureCookies lists cookie names to extract from Set-Cookie and forward.
	CaptureCookies []string `json:"capture_cookies,omitempty"`
	// StaticHeaders are fixed headers that don't change between sessions.
	StaticHeaders map[string]string `json:"static_headers,omitempty"`
	// ClearanceCookies are cookies obtained from a browser-based anti-bot
	// challenge solve. Persisted so subsequent requests can skip the browser.
	ClearanceCookies map[string]string `json:"clearance_cookies,omitempty"`
}

type TableRowField struct {
	Name      string `json:"name"`
	Row       int    `json:"row"` // 0-indexed row within the group
	Selector  string `json:"selector"`
	Attribute string `json:"attribute,omitempty"` // empty = text content
	Type      string `json:"type,omitempty"`      // "string" (default), "number"
	Required  bool   `json:"required,omitempty"`
}

type TableRowsConfig struct {
	Container string          `json:"container"`  // CSS selector for the <table> or <tbody>
	GroupSize int             `json:"group_size"` // number of <tr> rows per logical item
	Fields    []TableRowField `json:"fields"`     // which row + selector for each field
}

type Variable struct {
	Name    string `json:"name"`
	Source  string `json:"source"`
	Pattern string `json:"pattern"`
}