integration

type AccessFilter interface {
	// CanAccess checks if the current user can access the given URN.
	CanAccess(ctx context.Context, urn string) (bool, error)

	// FilterURNs filters a list of URNs to only those accessible by the current user.
	FilterURNs(ctx context.Context, urns []string) ([]string, error)
}

type AuditLogger interface {
	// LogToolCall logs a tool invocation.
	LogToolCall(ctx context.Context, tool string, params map[string]any, userID string) error
}

type ExecutionContext struct {
	// Tables maps DataHub URNs to their resolved table identifiers.
	Tables map[string]*TableIdentifier `json:"tables,omitempty"`

	// Connections lists the query engine connections involved.
	Connections []string `json:"connections,omitempty"`

	// Queries are relevant queries that involve these entities.
	Queries []ExecutionQuery `json:"queries,omitempty"`

	// Source indicates which provider supplied this context.
	Source string `json:"source,omitempty"`
}

type ExecutionQuery struct {
	// SQL is the query text.
	SQL string `json:"sql,omitempty"`

	// Sources are the source table URNs.
	Sources []string `json:"sources,omitempty"`

	// Targets are the target table URNs (for INSERT/CREATE).
	Targets []string `json:"targets,omitempty"`

	// ExecutedAt is when the query was last executed (if known).
	ExecutedAt *time.Time `json:"executed_at,omitempty"`

	// QueryID is the query engine's query identifier.
	QueryID string `json:"query_id,omitempty"`
}

type MetadataEnricher interface {
	// EnrichEntity adds custom metadata to an entity response.
	EnrichEntity(ctx context.Context, urn string, data map[string]any) (map[string]any, error)
}

type NoOpQueryProvider struct{}

type QueryExample struct {
	// Name is a short identifier for the example.
	Name string `json:"name"`

	// Description explains what the query does.
	Description string `json:"description,omitempty"`

	// SQL is the executable SQL statement.
	SQL string `json:"sql"`

	// Category classifies the example type.
	// Common values: "sample", "aggregation", "join", "filter", "common"
	Category string `json:"category,omitempty"`

	// Source indicates where this example came from.
	// Values: "generated", "history", "template", "documentation"
	Source string `json:"source,omitempty"`
}

type QueryProvider interface {
	// Name returns the provider name (e.g., "trino", "spark", "presto").
	// Used for logging, metrics, and source attribution.
	Name() string

	// ResolveTable maps a DataHub URN to a query engine table identifier.
	// Returns nil if the URN cannot be resolved to a queryable table.
	//
	// Example URN: urn:li:dataset:(urn:li:dataPlatform:trino,catalog.schema.table,PROD)
	// Returns: &TableIdentifier{Catalog: "catalog", Schema: "schema", Table: "table"}
	ResolveTable(ctx context.Context, urn string) (*TableIdentifier, error)

	// GetTableAvailability checks if a DataHub entity is available as a queryable table.
	// This is used to enrich search results with query availability status.
	// Returns nil if availability cannot be determined (not an error).
	GetTableAvailability(ctx context.Context, urn string) (*TableAvailability, error)

	// GetQueryExamples returns sample SQL queries for a DataHub entity.
	// Returns an empty slice if no examples are available (not an error).
	// Examples might include: SELECT samples, common aggregations, join patterns.
	GetQueryExamples(ctx context.Context, urn string) ([]QueryExample, error)

	// GetExecutionContext returns execution context for lineage bridging.
	// Given a set of DataHub URNs (e.g., from lineage), returns information
	// about how they relate to query execution (sources, targets, transformations).
	// Returns nil if no execution context is available (not an error).
	GetExecutionContext(ctx context.Context, urns []string) (*ExecutionContext, error)

	// Close releases any resources held by the provider.
	// Implementations should be idempotent.
	Close() error
}

type QueryProviderFunc struct {
	NameFn                 func() string
	ResolveTableFn         func(ctx context.Context, urn string) (*TableIdentifier, error)
	GetTableAvailabilityFn func(ctx context.Context, urn string) (*TableAvailability, error)
	GetQueryExamplesFn     func(ctx context.Context, urn string) ([]QueryExample, error)
	GetExecutionContextFn  func(ctx context.Context, urns []string) (*ExecutionContext, error)
	CloseFn                func() error
}

type TableAvailability struct {
	// Available indicates if the table exists and is queryable.
	Available bool `json:"available"`

	// Table is the resolved table identifier (nil if not available).
	Table *TableIdentifier `json:"table,omitempty"`

	// Connection is the query engine connection where the table is available.
	Connection string `json:"connection,omitempty"`

	// Error explains why the table is not available (if Available is false).
	Error string `json:"error,omitempty"`

	// LastChecked is when availability was last verified.
	LastChecked time.Time `json:"last_checked,omitempty"`

	// RowCount is an optional estimate of table rows (if known).
	RowCount *int64 `json:"row_count,omitempty"`

	// LastUpdated is when the table data was last modified (if known).
	LastUpdated *time.Time `json:"last_updated,omitempty"`
}

type TableIdentifier struct {
	// Connection is the named connection (empty for default).
	Connection string `json:"connection,omitempty"`

	// Catalog is the catalog/database name.
	Catalog string `json:"catalog"`

	// Schema is the schema name.
	Schema string `json:"schema"`

	// Table is the table name.
	Table string `json:"table"`
}

type URNResolver interface {
	// ResolveToDataHubURN converts an external identifier to a DataHub URN.
	ResolveToDataHubURN(ctx context.Context, externalID string) (string, error)
}