graphql

type Authenticator = upstreamauth.Authenticator

type Config struct {
	// EndpointURL is the full URL documents are POSTed to (e.g.
	// "https://datahub.example.com/api/graphql"). Required. Unlike the
	// API gateway's base_url this is the whole address, not a root
	// paths are joined to: a GraphQL endpoint has one address.
	EndpointURL string
	// Description is an optional human-readable description of the
	// connection, surfaced by ListConnections and so by the admin UI
	// and the list_connections tool. Empty falls back to the endpoint.
	Description string
	// ConnectionName is the audit-visible connection identifier and the
	// value passed in a tool's `connection` argument. Populated from
	// the toolkit instance name.
	ConnectionName string

	// AuthMode and the credential fields below carry the shared
	// upstream authentication policy. See internal/upstreamauth.
	AuthMode            string
	Credential          string
	CredentialPlacement string
	APIKeyHeader        string
	APIKeyParam         string
	Username            string
	Password            string
	OAuth2              OAuth2Config
	// SignedJWT carries the assertion parameters used when AuthMode is
	// AuthModeSignedJWT: the platform mints a short-lived JWT per call
	// from an identifier and a signing key issued out of band. Aliased
	// straight from the shared seam rather than mirrored, because
	// nothing in it is this kind's to define.
	SignedJWT SignedJWTConfig

	// ConnectTimeout caps the dial step on each call.
	ConnectTimeout time.Duration
	// CallTimeout caps the total per-call time.
	CallTimeout time.Duration
	// MaxResponseBytes is the upstream read cap.
	MaxResponseBytes int64
	// MaxInlineBytes is the most of a response returned through a tool
	// result. The read cap bounds it, so a connection whose
	// MaxResponseBytes is lower returns at most that.
	MaxInlineBytes int64
	// StaticHeaders are operator-configured headers attached to every
	// outbound request, in addition to whatever AuthMode contributes.
	// This is where an upstream's tenant or folder routing goes (Sage
	// X3's x-xtrem-endpoint, a vendor subscription key). The model
	// never sets or overrides these.
	StaticHeaders map[string]string
	// MTLSClientCertPEM is the PEM client certificate chain presented
	// during the TLS handshake.
	MTLSClientCertPEM string
	// MTLSClientKeyPEM is the PEM private key matching the certificate.
	// Encrypted at rest.
	MTLSClientKeyPEM string
	// TLSCABundlePEM is an optional PEM bundle of root CAs added to the
	// trust store for this connection's outbound requests.
	TLSCABundlePEM string
	// IdentityPassthrough forwards the acting caller's inbound bearer
	// token as the outbound Authorization header instead of applying
	// this connection's shared credential.
	IdentityPassthrough bool

	// SchemaValidation is SchemaValidationStrict (default) or
	// SchemaValidationWarn.
	SchemaValidation string
	// MaxQueryDepth caps the selection depth of a document the toolkit
	// will send. Defaults to DefaultMaxQueryDepth.
	MaxQueryDepth int
	// NamespaceDepth caps how many segments a dotted operation id may
	// have when the schema is walked into operations. Defaults to
	// gqlschema.DefaultNamespaceDepth.
	NamespaceDepth int
	// ReadOnly refuses every mutation document on this connection, for
	// every persona. It is the connection-level counterpart to a
	// persona's `deny` rule on the MUTATION method: an operator who
	// mounts an ERP for reporting sets it once here rather than in
	// every persona.
	ReadOnly bool
}

type DiscoverInput struct {
	Connection  string `json:"connection"`
	Query       string `json:"query,omitempty"`
	OperationID string `json:"operation_id,omitempty"`
	Limit       int    `json:"limit,omitempty"`
	Ranking     string `json:"ranking,omitempty"`
	Depth       int    `json:"depth,omitempty"`
}

type DiscoverOutput struct {
	Level      string            `json:"level"`
	Connection string            `json:"connection"`
	Operations []RankedOperation `json:"operations,omitempty"`
	Operation  *OperationDetail  `json:"operation,omitempty"`
	// SchemaHash and SchemaFetchedAt identify the schema version this
	// answer was read from, so a caller comparing two answers can see
	// whether the schema moved underneath them.
	SchemaHash      string `json:"schema_hash,omitempty"`
	SchemaFetchedAt string `json:"schema_fetched_at,omitempty"`
	// MatchedLexical and ShownSemantic report where relevance ended:
	// how many operations contain every token, and how many followed
	// them as neighbors by intent. Absent unless the call carried a
	// query.
	MatchedLexical *int   `json:"matched_lexical,omitempty"`
	ShownSemantic  *int   `json:"shown_semantic,omitempty"`
	Note           string `json:"note,omitempty"`
	Next           string `json:"next,omitempty"`
}

type Error struct {
	// Message is the upstream's own text. It is passed through
	// unchanged: for most GraphQL upstreams it is the only diagnosis
	// the caller will get.
	Message string `json:"message"`
	// Path is the response path the error occurred at, when the
	// upstream reports one.
	Path []any `json:"path,omitempty"`
	// Locations are the document positions the upstream blames.
	Locations []ErrorLocation `json:"locations,omitempty"`
	// Extensions is the upstream's own error metadata (an error code,
	// a classification), passed through as sent.
	Extensions map[string]any `json:"extensions,omitempty"`
}

type ErrorLocation struct {
	Line   int `json:"line"`
	Column int `json:"column"`
}

type ExportAsset struct {
	ID             string
	OwnerID        string
	OwnerEmail     string
	Name           string
	Description    string
	ContentType    string
	S3Bucket       string
	S3Key          string
	SizeBytes      int64
	Tags           []string
	Provenance     ExportProvenance
	SessionID      string
	IdempotencyKey string
}

type ExportAssetRef struct {
	ID        string
	SizeBytes int64
}

type ExportAssetStore interface {
	InsertExportAsset(ctx context.Context, asset ExportAsset) error
	GetByIdempotencyKey(ctx context.Context, ownerID, key string) (*ExportAssetRef, error)
}

type ExportConfig struct {
	MaxBytes       int64
	DefaultTimeout time.Duration
	MaxTimeout     time.Duration
}

type ExportDeps struct {
	AssetStore   ExportAssetStore
	VersionStore ExportVersionStore
	S3Client     ExportS3Client
	ShareCreator ExportShareCreator
	// ResourceLander lands a result in a managed resource by path instead of in
	// a new asset (#1663). nil leaves the asset destination the only one, which
	// is what a deployment with no managed-resource library has.
	ResourceLander toolkit.ResourceLander
	S3Bucket       string
	S3Prefix       string
	BaseURL        string
	Config         ExportConfig
	GetUserContext func(ctx context.Context) *ExportUserContext
}

type ExportProvenance struct {
	ToolCalls []ExportProvenanceCall
	SessionID string
	UserID    string
}

type ExportProvenanceCall struct {
	ToolName   string
	Timestamp  string
	Parameters map[string]any
}

type ExportS3Client interface {
	// PutObjectStream uploads body to bucket/key, returning the bytes
	// written.
	PutObjectStream(ctx context.Context, bucket, key string, body io.Reader, contentType string) (size int64, err error)
}

type ExportShareCreator interface {
	CreatePublicShare(ctx context.Context, assetID, createdBy string) (shareURL string, err error)
}

type ExportUserContext struct {
	UserID    string
	UserEmail string
	SessionID string
}

type ExportVersion struct {
	ID            string
	AssetID       string
	S3Key         string
	S3Bucket      string
	ContentType   string
	SizeBytes     int64
	CreatedBy     string
	ChangeSummary string
}

type ExportVersionStore interface {
	CreateExportVersion(ctx context.Context, version ExportVersion) (int, error)
}

type MultiConfig struct {
	DefaultName string
	Instances   map[string]Config
}

type OAuth2Config struct {
	// Grant is the OAuth flow: client_credentials or
	// authorization_code.
	Grant string
	// TokenURL is the upstream's token endpoint.
	TokenURL string
	// ClientID is the platform's registered client id.
	ClientID string
	// ClientSecret is the platform's registered client secret,
	// encrypted at rest.
	ClientSecret string
	// Scopes is an optional list of scopes to request.
	Scopes []string
	// EndpointAuthStyle is "header" (default) or "params".
	EndpointAuthStyle string
	// AuthorizationURL is the upstream's authorization endpoint,
	// required for the authorization_code grant.
	AuthorizationURL string
	// Prompt is an optional OIDC prompt parameter.
	Prompt string
}

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

type OperationDetail struct {
	OperationSummary
	// ArgumentDetails are the operation's arguments with their types,
	// descriptions, defaults and whether they are required.
	ArgumentDetails []gqlschema.Argument `json:"argument_details,omitempty"`
	// InputTypes expands the input-object types the arguments
	// reference, so a caller filling in a filter or a create payload
	// does not need a second lookup.
	InputTypes []gqlschema.InputType `json:"input_types,omitempty"`
	// ReturnShape is the return type's field tree, depth-limited.
	ReturnShape []gqlschema.FieldNode `json:"return_shape,omitempty"`
	// Skeleton is a document that validates against this connection's
	// schema and calls this operation, with every argument bound to a
	// variable. It is the load-bearing part of this level: it is the
	// difference between a correct selection on the first try and
	// several calls spent on validation errors.
	Skeleton string `json:"skeleton"`
	// Variables is a JSON object carrying one entry per required
	// argument, ready to edit and pass as graphql_query's variables.
	// An optional argument is declared in the skeleton but absent here,
	// so leaving it out sends the schema's own default; add its key to
	// set it.
	Variables string `json:"variables"`
}

type OperationSummary struct {
	// OperationID is the kind-prefixed dotted id
	// ("query:masterData.product.query"). It is what operation_id
	// takes.
	OperationID string `json:"operation_id"`
	// Kind is QUERY or MUTATION. It is also the method a persona rule
	// names for this operation.
	Kind string `json:"kind"`
	// Path is the path a persona rule names this operation under: the
	// dotted id with dots as slashes.
	Path string `json:"path"`
	// Summary is the descriptions the schema carries along the
	// operation's path.
	Summary string `json:"summary,omitempty"`
	// ReturnType is the rendered type the operation returns.
	ReturnType string `json:"return_type,omitempty"`
	// Arguments are the operation's argument names, rendered
	// "name: Type" so a caller can see what it takes without a second
	// call.
	Arguments []string `json:"arguments,omitempty"`
	// Deprecated reports the schema marking this operation
	// @deprecated.
	Deprecated bool `json:"deprecated,omitempty"`
}

type PaginateInput struct {
	// Items is the dotted path, inside the response's data object, of
	// the array merged across pages
	// ("masterData.product.query.edges", "searchAcrossEntities.results").
	// Required.
	Items string `json:"items"`
	// CursorVariable is the document variable the next page's cursor is
	// bound to ("after", "scrollId"). Required: the cursor goes back as
	// a variable, so the document itself is unchanged between pages.
	CursorVariable string `json:"cursor_variable"`
	// NextCursorPath is the dotted path, inside data, holding the next
	// page's cursor. Defaults to the Relay pageInfo.endCursor beside
	// the items array.
	NextCursorPath string `json:"next_cursor_path,omitempty"`
	// HasNextPath is the dotted path, inside data, of a boolean saying
	// whether another page exists. Defaults to the Relay
	// pageInfo.hasNextPage beside the items array. An upstream that
	// signals the end by a null cursor alone needs no such field: the
	// walk stops on an absent cursor either way.
	HasNextPath string `json:"has_next_path,omitempty"`
	// MaxPages bounds the walk. Defaults to DefaultMaxPages.
	MaxPages int `json:"max_pages,omitempty"`
}

type PaginationReport struct {
	// PagesFetched is how many pages were read.
	PagesFetched int `json:"pages_fetched"`
	// ItemsMerged is the length of the merged array.
	ItemsMerged int `json:"items_merged"`
	// StoppedBy is why the walk ended.
	StoppedBy string `json:"stopped_by"`
	// NextCursor is the cursor the next page would have used, present
	// when the walk stopped at its page bound rather than at the end.
	NextCursor string `json:"next_cursor,omitempty"`
}

type QueryInput struct {
	Connection     string          `json:"connection"`
	Query          string          `json:"query"`
	Variables      json.RawMessage `json:"variables,omitempty"`
	OperationName  string          `json:"operation_name,omitempty"`
	TimeoutSeconds int             `json:"timeout_seconds,omitempty"`
	Paginate       *PaginateInput  `json:"paginate,omitempty"`
}

type QueryOutput struct {
	Connection string `json:"connection"`
	// Kind is QUERY or MUTATION: the operation kind that executed, and
	// the method the persona rules authorized it under.
	Kind string `json:"kind"`
	// OperationName is the operation that ran, when the document named
	// one.
	OperationName string `json:"operation_name,omitempty"`
	// Operations are the dotted operation ids this document invoked,
	// the same ids graphql_discover reports and persona rules name.
	Operations []string `json:"operations,omitempty"`
	// Status is the HTTP status the endpoint answered with. It is
	// almost always 200, including for a failure: what decides the
	// outcome is upstream_error.
	Status int `json:"status"`
	// Data is the GraphQL data object, as sent. Present even alongside
	// errors: a partial result is preserved rather than discarded.
	Data json.RawMessage `json:"data,omitempty"`
	// Errors is the response's errors array, passed through unchanged.
	Errors []Error `json:"errors,omitempty"`
	// Extensions is the response's extensions object, passed through.
	Extensions map[string]any `json:"extensions,omitempty"`
	// UpstreamError reports a call that failed however it was
	// transported: a non-2xx, or a 200 carrying errors. It is what the
	// platform's audit, call catalog and metrics classify the call on.
	UpstreamError bool `json:"upstream_error"`
	// ValidationWarnings are the schema violations found in a
	// connection whose schema_validation is warn. Empty under strict,
	// where a violation refuses the call instead.
	ValidationWarnings []string `json:"validation_warnings,omitempty"`
	// DataBytes is the size of the data read.
	DataBytes int `json:"data_bytes"`
	// DataTruncated reports data withheld because the rendered result
	// would exceed this connection's max_inline_bytes. A cut JSON
	// document cannot be parsed, so the data is omitted rather than
	// halved; export_arguments carries the call that streams it whole.
	DataTruncated bool `json:"data_truncated,omitempty"`
	// ExportArguments is the graphql_export call that writes this same
	// result to an asset, present when the data did not fit inline.
	ExportArguments map[string]any `json:"export_arguments,omitempty"`
	// Pagination reports a walk that ran.
	Pagination *PaginationReport `json:"pagination,omitempty"`
	// Note explains anything that changed the answer.
	Note string `json:"note,omitempty"`
}

type RankedConnectionOperation struct {
	Connection string
	Operation  gqlschema.Operation
	Score      float64
}

type RankedOperation struct {
	OperationSummary
	Score        *float64 `json:"score,omitempty"`
	LexicalMatch *bool    `json:"lexical_match,omitempty"`
}

type RankingMode string

type RoutePolicy interface {
	Allow(ctx context.Context, connection, method, path, template string) (allowed bool, reason string)
}

type SchemaInfo struct {
	Connection     string    `json:"connection"`
	Hash           string    `json:"schema_hash,omitempty"`
	Source         string    `json:"source,omitempty"`
	FetchedAt      time.Time `json:"fetched_at,omitzero"`
	OperationCount int       `json:"operation_count"`
	Error          string    `json:"error,omitempty"`
}

type SchemaStore interface {
	// GetSchema returns the stored schema for a connection, or an error
	// wrapping ErrSchemaNotFound when there is none.
	GetSchema(ctx context.Context, connection string) (StoredSchema, error)
	// PutSchema writes a connection's schema, replacing any previous
	// one.
	PutSchema(ctx context.Context, s StoredSchema) error
	// DeleteSchema removes a connection's schema, called when the
	// connection is deleted.
	DeleteSchema(ctx context.Context, connection string) error
}

type SignedJWTConfig = upstreamauth.SignedJWTConfig

type StoredSchema struct {
	// Connection is the connection name the schema belongs to.
	Connection string
	// Hash is the sha256 of the SDL, hex-encoded. An operation index
	// and its embeddings are keyed on it.
	Hash string
	// SDL is the schema text.
	SDL string
	// Source is SchemaSourceIntrospection or SchemaSourceUpload.
	Source string
	// FetchedAt is when the schema was read or uploaded.
	FetchedAt time.Time
}

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

type VectorReader interface {
	// LoadVectors returns the persisted vectors for one connection's
	// schema version, keyed by operation id. An empty map means the
	// schema has not been indexed yet; ranking falls back to lexical
	// and says so.
	LoadVectors(ctx context.Context, connection, schemaHash string) (map[string][]float32, error)
}