operations

type DocClient interface {
	Export(ctx context.Context, cfg *DocumentExport) error
}

type DocumentExport struct {
	// FileID is the external file identifier to export
	FileID string `json:"fileId"`
	// HTML is the exported document content as an embeddable iframe string (populated in the response)
	HTML string `json:"html,omitempty"`
	// PDF is the exported document content as raw PDF bytes (populated in the response)
	PDF []byte `json:"pdf,omitempty"`
	// MimeType is the content type of the downloaded file
	MimeType string `json:"mimeType,omitempty"`
	// Name is the file name without extension
	Name string `json:"name,omitempty"`
}

type Envelope struct {
	types.ExecutionMetadata
	// Config is the operation configuration payload
	Config json.RawMessage `json:"config,omitempty"`
	// ForceClientRebuild requests client cache bypass
	ForceClientRebuild bool `json:"forceClientRebuild,omitempty"`
}

type IngestContext struct {
	// Registry is the integration definition registry used to resolve mappings and definitions
	Registry *registry.Registry
	// DB is the ent client used for persistence
	DB *ent.Client
	// Runtime is the Gala instance used for async emit; nil on the synchronous persist path
	Runtime *gala.Gala
	// Integration is the integration record being ingested into
	Integration *ent.Integration
}

type IngestOptions struct {
	// DirectorySyncRunID groups all directory-related ingest records from one sync batch
	DirectorySyncRunID string
	// SkipDirectorySyncRunFinalization instructs the processor not to finalize the directory sync run after processing
	SkipDirectorySyncRunFinalization bool
	// Source identifies the mechanism that produced the ingest data (e.g. webhook, poll, manual)
	Source integrationgenerated.IntegrationIngestSource
	// RunID is a caller-supplied correlation identifier for the overall operation run
	RunID string
	// Webhook is the webhook name or identifier that triggered this ingest
	Webhook string
	// WebhookEvent is the event type reported by the webhook provider
	WebhookEvent string
	// DeliveryID is the provider-assigned delivery identifier; used for deduplication
	DeliveryID string
	// WorkflowMeta carries workflow instance context
	WorkflowMeta *types.WorkflowMeta
}

type ReconcileEnvelope struct {
	types.ExecutionMetadata
	// Schedule is the adaptive scheduling state carried across cycles
	Schedule gala.ScheduleState `json:"schedule"`
}

type ReconcileHandler func(context.Context, ReconcileEnvelope) (int, error)

type RunResult struct {
	// Status is the terminal run status
	Status enums.IntegrationRunStatus
	// Summary is the optional summary text stored on the run
	Summary string
	// Error is the optional terminal error text stored on the run
	Error string
	// Metrics is the structured metrics payload stored on the run
	Metrics map[string]any
}

type ScheduledListenerConfig[T any] struct {
	// Runtime is the Gala instance to register on
	Runtime *gala.Gala
	// Topic is the Gala topic name
	Topic gala.TopicName
	// Name is the stable listener name
	Name string
	// Schedule controls adaptive interval computation
	Schedule gala.Schedule
	// Handle is the handler invoked each cycle, returning the delta for scheduling
	Handle func(context.Context, T) (int, error)
	// State extracts the ScheduleState from the envelope
	State func(T) gala.ScheduleState
	// Wrap builds a new envelope carrying the updated ScheduleState
	Wrap func(T, gala.ScheduleState) T
	// PrepareEmit optionally enriches the context and headers before re-emitting
	PrepareEmit func(context.Context, T) (context.Context, gala.Headers)
	// ShouldCancel optionally classifies an execution error; when it returns
	// true the cycle is cancelled immediately without scheduling a retry
	ShouldCancel func(context.Context, T, error) bool
	// ScheduleOverride optionally returns a per-envelope schedule that
	// overrides the default; returning nil falls back to the config-level Schedule
	ScheduleOverride func(T) *gala.Schedule
}

type UserInput struct {
	// Primary marks this installation as the authoritative source for live document exports
	Primary bool `json:"primary,omitempty" jsonschema:"title=Primary"`
}

type WebhookEnvelope struct {
	types.ExecutionMetadata
	// Payload is the raw webhook request body
	Payload json.RawMessage `json:"payload"`
	// Headers contains the inbound HTTP request headers
	Headers map[string]string `json:"headers,omitempty"`
}