datasource

type CalendarSourceConfig struct {
	Enabled     bool     `yaml:"enabled,omitempty" toml:"enabled,omitempty"`
	CalendarIDs []string `yaml:"calendar_ids,omitempty" toml:"calendar_ids,omitempty"`
}

type Config struct {
	// Enabled turns the data sources layer on or off. When false, no sync
	// runs and no connector is instantiated for vectorization.
	Enabled bool `yaml:"enabled,omitempty" toml:"enabled,omitempty"`

	// SyncInterval is how often the sync job runs (e.g. "15m", "1h"). When
	// empty or zero, sync is on-demand only (e.g. via a tool or admin API).
	SyncInterval time.Duration `yaml:"sync_interval,omitempty" toml:"sync_interval,omitempty"`

	// SearchKeywords limits which items are indexed: only items whose content or
	// metadata contains at least one of these keywords (case-insensitive) are
	// embedded. Up to MaxSearchKeywords (10). When empty, all items are indexed.
	SearchKeywords []string `yaml:"search_keywords,omitempty" toml:"search_keywords,omitempty"`

	// GDrive scopes vectorization to the given folder IDs. Credentials come
	// from the main [google_drive] (or env). Omit or set Enabled false to skip.
	GDrive *GDriveSourceConfig `yaml:"gdrive,omitempty" toml:"gdrive,omitempty"`

	// Gmail scopes vectorization to the given labels. Credentials come from
	// the email/Gmail config. Omit or set Enabled false to skip.
	Gmail *GmailSourceConfig `yaml:"gmail,omitempty" toml:"gmail,omitempty"`

	// Slack scopes vectorization to the given channel IDs. Omit or set
	// Enabled false to skip.
	Slack *SlackSourceConfig `yaml:"slack,omitempty" toml:"slack,omitempty"`

	// Linear scopes vectorization to the given team IDs. Omit or set
	// Enabled false to skip.
	Linear *LinearSourceConfig `yaml:"linear,omitempty" toml:"linear,omitempty"`

	// Calendar scopes vectorization to the given calendar IDs. Omit or set
	// Enabled false to skip.
	Calendar *CalendarSourceConfig `yaml:"calendar,omitempty" toml:"calendar,omitempty"`

	// Jira scopes vectorization to the given project keys. Omit or set
	// Enabled false to skip. Requires a Jira MCP server in [mcp] config.
	Jira *JiraSourceConfig `yaml:"jira,omitempty" toml:"jira,omitempty"`

	// Confluence scopes vectorization to the given space keys. Omit or set
	// Enabled false to skip. Requires a Confluence MCP server in [mcp] config.
	Confluence *ConfluenceSourceConfig `yaml:"confluence,omitempty" toml:"confluence,omitempty"`

	// ServiceNow scopes vectorization to the given table names. Omit or set
	// Enabled false to skip. Requires a ServiceNow MCP server in [mcp] config.
	ServiceNow *ServiceNowSourceConfig `yaml:"servicenow,omitempty" toml:"servicenow,omitempty"`

	// ExternalSources holds additional SourceConfig entries registered at
	// runtime (e.g. by SCM config). These are keyed by source name and
	// participate in ScopeFromConfig/EnabledSourceNames automatically.
	ExternalSources map[string]SourceConfig `yaml:"-" toml:"-"`
}

type ConfluenceSourceConfig struct {
	Enabled   bool     `yaml:"enabled,omitempty" toml:"enabled,omitempty"`
	SpaceKeys []string `yaml:"space_keys,omitempty" toml:"space_keys,omitempty"`
	MCPServer string   `yaml:"mcp_server,omitempty" toml:"mcp_server,omitempty"`
}

type ConnectorFactory func(ctx context.Context, opts ConnectorOptions) DataSource

type ConnectorOptions struct {
	// SecretProvider is the application's secret provider, passed as any to
	// avoid importing pkg/security from the datasource package. Each factory
	// type-asserts to security.SecretProvider before use.
	SecretProvider any
	// DocParser is the optional document parsing provider (e.g. Docling Serve)
	// for extracting text from binary files (PDF, DOCX, images). When nil,
	// connectors skip document parsing and produce header-only items for binary files.
	DocParser docparser.Provider
	// ExtraInt holds integer extras keyed by name (e.g. "max_depth").
	ExtraInt map[string]int
	// ExtraString holds string extras keyed by name (e.g. "credentials_file", "scm_provider").
	ExtraString map[string]string
}

type DataSource interface {
	// Name returns the source identifier (e.g. "gdrive", "gmail", "slack", "linear", "github", "calendar").
	// It is used as the "source" field in NormalizedItem and in metadata for filtering.
	Name() string

	// ListItems returns all items in scope for this source. Scope is
	// source-specific (e.g. folder IDs, channel IDs, label IDs) and is
	// supplied when the connector is constructed from config. The caller
	// (sync pipeline) then maps each NormalizedItem to a vector.BatchItem
	// and upserts into the vector store.
	ListItems(ctx context.Context, scope Scope) ([]NormalizedItem, error)
}

type GDriveSourceConfig struct {
	Enabled   bool     `yaml:"enabled,omitempty" toml:"enabled,omitempty"`
	FolderIDs []string `yaml:"folder_ids,omitempty" toml:"folder_ids,omitempty"`
}

type GmailSourceConfig struct {
	Enabled  bool     `yaml:"enabled,omitempty" toml:"enabled,omitempty"`
	LabelIDs []string `yaml:"label_ids,omitempty" toml:"label_ids,omitempty"`
}

type JiraSourceConfig struct {
	Enabled     bool     `yaml:"enabled,omitempty" toml:"enabled,omitempty"`
	ProjectKeys []string `yaml:"project_keys,omitempty" toml:"project_keys,omitempty"`
	MCPServer   string   `yaml:"mcp_server,omitempty" toml:"mcp_server,omitempty"`
}

type LinearSourceConfig struct {
	Enabled bool     `yaml:"enabled,omitempty" toml:"enabled,omitempty"`
	TeamIDs []string `yaml:"team_ids,omitempty" toml:"team_ids,omitempty"`
}

type ListItemsSince interface {
	DataSource
	// ListItemsSince returns items in scope that were updated after the given time.
	ListItemsSince(ctx context.Context, scope Scope, since time.Time) ([]NormalizedItem, error)
}

type NormalizedItem struct {
	// ID is stable and unique across all sources (e.g. "gdrive:fileId", "slack:channelId:ts").
	ID string
	// Source is the same as DataSource.Name() (e.g. "gdrive", "slack").
	Source string
	// SourceRef identifies the origin for source material lookup (Type + RefID).
	// When set, sync stores source_type and source_ref_id in vector metadata so
	// search results can cite and verify the original (e.g. open Gmail message, Drive file).
	SourceRef *SourceRef
	// UpdatedAt is used for incremental sync and ordering.
	UpdatedAt time.Time
	// Content is the text to embed (title + body, snippet, or full text).
	Content string
	// Metadata holds optional keys (title, author, type, product, category, etc.)
	// that can be used for SearchWithFilter when AllowedMetadataKeys permits.
	Metadata map[string]string
}

type Scope struct {
	// Items maps source name → scope values (e.g. "gdrive" → folder IDs,
	// "slack" → channel IDs, "jira" → project keys).
	Items map[string][]string
}

type ServiceNowSourceConfig struct {
	Enabled    bool     `yaml:"enabled,omitempty" toml:"enabled,omitempty"`
	TableNames []string `yaml:"table_names,omitempty" toml:"table_names,omitempty"`
	MCPServer  string   `yaml:"mcp_server,omitempty" toml:"mcp_server,omitempty"`
}

type SlackSourceConfig struct {
	Enabled    bool     `yaml:"enabled,omitempty" toml:"enabled,omitempty"`
	ChannelIDs []string `yaml:"channel_ids,omitempty" toml:"channel_ids,omitempty"`
}

type SourceConfig interface {
	// IsEnabled returns true when this source is turned on and has meaningful scope.
	IsEnabled() bool
	// ScopeValues returns the scope items for this source (e.g. folder IDs,
	// channel IDs, project keys). An empty slice means no scope is configured.
	ScopeValues() []string
}

type SourceRef struct {
	// Type is the source type (e.g. "gmail", "gdrive", "slack", "linear", "github", "calendar").
	Type string
	// RefID is the ID in that system to look up the original (e.g. message ID, file ID, channel:ts).
	RefID string
}

type SyncState map[string]string