sdk

type Action[T any] struct{ Name string }

type AdminUI struct {
	// Title is the sidebar label and the page heading.
	Title string `json:"title"`
	// Entry is the HTML file under ui/ (default "index.html").
	Entry string `json:"entry,omitempty"`
	// Roles may open the page; empty means owner only.
	Roles []string `json:"roles,omitempty"`
}

type AgentFirstCrawlEvent struct {
	EntityID    string     `json:"entity_id"`
	AgentID     string     `json:"agent_id"`
	Operator    string     `json:"operator"`
	Purpose     string     `json:"purpose"`
	FirstAt     time.Time  `json:"first_at"`
	PublishedAt *time.Time `json:"published_at,omitempty"`
}

type AgentHitEvent struct {
	AgentID      string    `json:"agent_id"`
	Operator     string    `json:"operator"`
	Purpose      string    `json:"purpose"`
	Verification string    `json:"verification"`
	Method       string    `json:"method"`
	Path         string    `json:"path"`
	EntityID     string    `json:"entity_id"`
	Source       string    `json:"source"`
	Status       int       `json:"status"`
	Bytes        int       `json:"bytes"`
	DurationMS   int       `json:"duration_ms"`
	OccurredAt   time.Time `json:"occurred_at"`
}

type Alternate struct {
	Rel      string `json:"rel"`
	HrefLang string `json:"hreflang"`
	Href     string `json:"href"`
}

type Block struct {
	ID      string         `json:"id"`
	Type    string         `json:"type"`
	Title   string         `json:"title,omitempty"`
	Fields  map[string]any `json:"fields,omitempty"`
	Content map[string]any `json:"content,omitempty"`
	Hidden  bool           `json:"hidden,omitempty"`
}

type BuilderDataItem struct {
	Title       string            `json:"title,omitempty"`
	URL         string            `json:"url,omitempty"`
	Excerpt     string            `json:"excerpt,omitempty"`
	Image       string            `json:"image,omitempty"`
	Category    string            `json:"category,omitempty"`
	Author      string            `json:"author,omitempty"`
	AuthorURL   string            `json:"author_url,omitempty"`
	PublishedAt string            `json:"published_at,omitempty"`
	Attrs       map[string]string `json:"attrs,omitempty"`
}

type BuilderDataQuery struct {
	ID     string `json:"id"`
	Source string `json:"source"`
	Limit  int    `json:"limit,omitempty"`
}

type BuilderDataRequest struct {
	Path       string              `json:"path,omitempty"`
	Language   string              `json:"language,omitempty"`
	SchemaSlug string              `json:"schema_slug,omitempty"`
	EntityID   string              `json:"entity_id,omitempty"`
	Requests   []BuilderDataQuery  `json:"requests,omitempty"`
	Results    []BuilderDataResult `json:"results,omitempty"`
}

type BuilderDataResult struct {
	ID    string            `json:"id"`
	Value string            `json:"value,omitempty"`
	Items []BuilderDataItem `json:"items,omitempty"`
	Error string            `json:"error,omitempty"`
}

type BuilderSource struct {
	// Name is the source's short name, unique within the plugin.
	Name string `json:"name"`
	// Label is shown in the editor (1 to 60 characters).
	Label string `json:"label"`
	// Kind is BuilderSourceValue (one string for a prop) or
	// BuilderSourceItems (a list for a loop).
	Kind string `json:"kind"`
	// Class is the prop class a value source fits: text, url or image
	// (default text). Only for value sources.
	Class string `json:"class,omitempty"`
}

type CallRequest struct {
	Fn   string          `json:"fn"`
	Args json.RawMessage `json:"args,omitempty"`
}

type CallResponse struct {
	OK     bool            `json:"ok"`
	Result json.RawMessage `json:"result,omitempty"`
	Error  *HostError      `json:"error,omitempty"`
}

type CronEvent struct {
	Name        string `json:"name"`
	ScheduledAt string `json:"scheduled_at"` // RFC 3339
}

type CronJob struct {
	Name  string `json:"name"`
	Every string `json:"every"`
}

type EntityDraft struct {
	Operation  string `json:"operation"`
	ID         string `json:"id"`
	SchemaSlug string `json:"schema_slug"`
	Name       string `json:"name"`
	Slug       string `json:"slug"`
	// Locale is the entity's BCP 47 tag; the host does not read it back.
	Locale     string          `json:"locale,omitempty"`
	Attributes json.RawMessage `json:"attributes"`
}

type EntityEvent struct {
	ID         string `json:"id"`
	SchemaSlug string `json:"schema_slug"`
	Slug       string `json:"slug"`
	Locale     string `json:"locale"`
	Name       string `json:"name"`
	Status     string `json:"status"`
	Version    int    `json:"version"`
}

type EntityRef struct {
	ID         string `json:"id"`
	SchemaSlug string `json:"schema_slug"`
	Slug       string `json:"slug"`
	Locale     string `json:"locale"`
	Name       string `json:"name"`
	Status     string `json:"status"`
	Version    int    `json:"version"`
}

type EntitySummary struct {
	ID         string `json:"id"`
	SchemaSlug string `json:"schema_slug"`
	Slug       string `json:"slug"`
	Locale     string `json:"locale"`
	Name       string `json:"name"`
}

type Filter[T any] struct{ Name string }

type FormSubmittedEvent struct {
	FormID       string         `json:"form_id"`
	FormSlug     string         `json:"form_slug"`
	SubmissionID string         `json:"submission_id"`
	Fields       map[string]any `json:"fields"`
	SourcePath   string         `json:"source_path,omitempty"`
	SubmittedAt  time.Time      `json:"submitted_at"`
}

type HTTPRequest struct {
	Method string `json:"method"`
	Path   string `json:"path"` // below /api/v1/p/<plugin> or /p/<plugin>, starts with "/"; always the path the route was matched and authorised on
	// Pattern is the manifest route path that matched (e.g. "/items/{id}") and
	// PathValues its wildcard values, so a plugin need not re-route by hand.
	Pattern    string              `json:"pattern,omitempty"`
	PathValues map[string]string   `json:"path_values,omitempty"`
	Query      map[string][]string `json:"query,omitempty"`
	Headers    map[string]string   `json:"headers,omitempty"` // allowlisted request headers, lower-case names
	Body       string              `json:"body,omitempty"`
	BodyB64    string              `json:"body_b64,omitempty"` // set instead of Body when the body is not UTF-8
	User       *HTTPUser           `json:"user,omitempty"`     // nil on public routes
}

type HTTPResponse struct {
	Status  int               `json:"status,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
	Body    string            `json:"body,omitempty"`
	BodyB64 string            `json:"body_b64,omitempty"`
}

type HTTPUser struct {
	ID   string `json:"id"`
	Role string `json:"role"`
}

type HeadContext struct {
	Path             string    `json:"path"`
	Language         string    `json:"language"`
	SchemaSlug       string    `json:"schema_slug"`
	EntityID         string    `json:"entity_id"`
	Tags             []HeadTag `json:"tags,omitempty"`
	ReplaceSiteGraph bool      `json:"replace_site_graph"`
}

type HeadTag struct {
	Kind   string            `json:"kind"`
	Attrs  map[string]string `json:"attrs,omitempty"`
	JSONLD json.RawMessage   `json:"jsonld,omitempty"`
}

type HostError struct {
	Code       string `json:"code"`
	Capability string `json:"capability,omitempty"`
	Message    string `json:"message"`
}

type ImportEvent struct {
	Source  string `json:"source"`
	Created int    `json:"created"`
	Updated int    `json:"updated"`
	Failed  int    `json:"failed"`
}

type JSONLDDoc struct {
	Entity  EntityRef      `json:"entity"`
	BaseURL string         `json:"base_url"`
	Doc     map[string]any `json:"doc"`
}

type Limits struct {
	// MemoryPages is the cap on each wasm linear memory, in 64 KiB pages.
	// A standard Go guest needs at least MinMemoryPages.
	MemoryPages uint32 `json:"memory_pages,omitempty"`
	// HookTimeoutsMS overrides the time one call of a hook may run, in
	// milliseconds. Keys are hook names ("render.page"), or "http_handle",
	// "on_cron_<job>" and "func_<name>" for the other exports. A hook not
	// listed gets DefaultFilterTimeoutMS (filters and template funcs) or
	// DefaultActionTimeoutMS (actions, cron, routes). Zero is refused: a
	// guest without a deadline cannot be stopped.
	HookTimeoutsMS map[string]uint64 `json:"hook_timeouts_ms,omitempty"`
	// MaxInstances caps concurrent calls (and so live instances) of the plugin.
	MaxInstances int `json:"max_instances,omitempty"`
	// MaxOutputBytes caps what one call may return. Larger output fails the
	// call (fail open); it never reaches the JSON decoder.
	MaxOutputBytes uint32 `json:"max_output_bytes,omitempty"`
}

type Manifest struct {
	Name        string `json:"name"`
	Version     string `json:"version"` // the plugin's own semver
	SDK         string `json:"sdk"`     // SDK range the plugin was built against, e.g. "^0.5"
	Description string `json:"description,omitempty"`

	// Config is handed to the guest (pdk.GetConfig).
	Config map[string]string `json:"config,omitempty"`

	// AllowedHosts is the plugin's outbound HTTP allowlist for http.fetch
	// (exact hosts, "*.example.com", "host:port"). "*" means any public
	// address on ports 80 and 443 and needs the http.fetch.any permission,
	// which the owner grants separately. Without the http.fetch permission
	// granted it has no effect.
	AllowedHosts []string `json:"allowed_hosts,omitempty"`

	// Permissions are the capabilities the plugin asks for (see Permissions).
	// The owner grants them; nothing is granted by default.
	Permissions []Permission `json:"permissions,omitempty"`

	// Routes are served under /api/v1/p/<name>/... (signed in, CSRF, roles)
	// or, with Public set, /p/<name>/... (anonymous, rate limited), by the
	// plugin's `http_handle` export.
	Routes []Route `json:"routes,omitempty"`

	// Cron lists scheduled calls of the plugin's `on_cron_<name>` exports.
	Cron []CronJob `json:"cron,omitempty"`

	// Cookies are the cookie names a render.page filter may read and set.
	Cookies []string `json:"cookies,omitempty"`

	// RenderPage tunes the render.page filter (see PageOptions).
	RenderPage *PageOptions `json:"render_page,omitempty"`

	// Funcs are template functions: the theme calls plugin_<name>_<func>
	// and the host calls the plugin's `func_<func>` export with JSON args.
	Funcs []string `json:"funcs,omitempty"`

	// UI is an optional admin page the plugin ships in its package's ui/
	// directory. It runs in a sandboxed iframe and reaches the host only
	// through a bridge limited to the plugin's own routes and granted host
	// functions.
	UI *AdminUI `json:"ui,omitempty"`

	// BuilderSources declares the data sources the plugin answers through the
	// builder.data filter (at most MaxBuilderSources). A source's id in the
	// builder is ext.<plugin>.<name>. Needs the builder.data permission.
	BuilderSources []BuilderSource `json:"builder_sources,omitempty"`

	Limits Limits `json:"limits,omitempty"`

	// SettingsSchema is an optional JSON Schema (draft 2020-12) object
	// describing the plugin's settings.
	SettingsSchema json.RawMessage `json:"settings_schema,omitempty"`
}

type PageContext struct {
	Path       string            `json:"path"`
	Cookies    map[string]string `json:"cookies"`
	Entity     *EntitySummary    `json:"entity,omitempty"`
	Blocks     []Block           `json:"blocks"`
	Hide       []string          `json:"hide,omitempty"`
	SetCookies []SetCookie       `json:"set_cookies,omitempty"`
}

type PageOptions struct {
	// FullBlocks sends every block with its whole content (the pre-0.9
	// payload). It is slower: the cost of a call grows with the page's size.
	FullBlocks bool `json:"full_blocks,omitempty"`
}

type Permission = string

type Reject struct{ Reason string }

type Route struct {
	Method string `json:"method"`
	Path   string `json:"path"`
	// Public routes are mounted at /p/<name> and need no sign-in.
	Public bool `json:"public,omitempty"`
	// Roles may call a non-public route; empty means owner only.
	Roles []string `json:"roles,omitempty"`
}

type SetCookie struct {
	Name   string `json:"name"`
	Value  string `json:"value"`
	MaxAge int    `json:"max_age,omitempty"`
	Path   string `json:"path,omitempty"`
}

type SitemapURL struct {
	Loc        string      `json:"loc"`
	LastMod    string      `json:"lastmod"`
	ChangeFreq string      `json:"changefreq"`
	Priority   float64     `json:"priority"`
	Alternates []Alternate `json:"alternates,omitempty"`
}

type SitemapURLs struct {
	Group    string       `json:"group"`
	Language string       `json:"language"`
	Add      []SitemapURL `json:"add"`
}