connectors

type Communication interface {
	// Verify checks authentication (e.g. auth.test) without sending messages.
	Verify(ctx context.Context) error
	// VerifyUser checks that an external user exists in the authorised account.
	VerifyUser(ctx context.Context, userID string) error
	// Run receives events until ctx is cancelled. It reports connection health
	// through Healthy.
	Run(ctx context.Context, sink IngressSink) error
	// Healthy reports whether the ingress connection is currently established.
	Healthy() (bool, string)
	// Send delivers a message and returns the external receipt (e.g. message ts).
	Send(ctx context.Context, msg OutboundMessage) (string, error)
}

type Config struct {
	OrganizationID string
	Key            string // connection key
	Adapter        string
	AccountID      string
	// Endpoint overrides the service base URL (used for fakes and self-hosted).
	Endpoint string
	Secret   map[string]string
	Extra    map[string]string
	// Model describes a model connection's endpoint (compiled defaults applied).
	Model *spec.ModelEndpoint
	// ModelUses are the models and APIs seats use through a model
	// connection; readiness checks them.
	ModelUses []ModelUse
	HTTP      *http.Client
}

type Credential struct {
	Username  string
	Token     string
	ExpiresAt time.Time
	Revocable bool
	// Data is a non-token credential, e.g. a browser storage state.
	Data json.RawMessage
}

type CredentialIssuer interface {
	IssueCredential(ctx context.Context, scope CredentialScope) (Credential, error)
	// RevokeCredential invalidates an issued credential where the service
	// supports it (Credential.Revocable).
	RevokeCredential(ctx context.Context, token string) error
}

type CredentialScope struct {
	Repos       []string
	Permissions map[string]string
}

type HTTPIngress interface {
	Handler() http.Handler
}

type InboundEvent struct {
	// EventID is the provider's stable event identity for deduplication.
	EventID string
	// AccountID is the verified installation or workspace identity.
	AccountID string
	UserID    string
	ChannelID string
	// ThreadRef identifies the external conversation (e.g. channel or thread ts).
	ThreadRef string
	Text      string
	MessageTS string
}

type IngressSink interface {
	Accept(ctx context.Context, connection string, ev InboundEvent) error
}

type Model interface {
	Verify(ctx context.Context) error
	// Proxy returns a handler serving the provider API with the credential
	// injected. The incoming request path has the platform prefix removed.
	Proxy() http.Handler
}

type ModelUse struct{ ID, API string }

type OutboundMessage struct {
	ExternalUserID string
	ChannelID      string
	ThreadRef      string
	Text           string
	// IdempotencyKey is the platform operation id.
	IdempotencyKey string
}

type Resolved struct {
	Values map[string]string
	// Version identifies the stored version (Kubernetes resourceVersion,
	// Vault KV version). It is not secret and may change without the
	// content changing, for example on a metadata-only update.
	Version string
	// Digest identifies the content: it changes exactly when a value
	// changes. It is a hash, safe to keep in memory, never logged.
	Digest string
}

type Result struct {
	Receipt string          `json:"receipt"`
	Data    json.RawMessage `json:"data"`
}

type SecretWatcher interface {
	Watch(ctx context.Context, notify func(ref string)) error
}

type Secrets interface {
	Resolve(ctx context.Context, ref string) (Resolved, error)
}

type Tracker interface {
	Verify(ctx context.Context) error
	// Invoke performs an operation. operationID is embedded in created records
	// where the API has no idempotency key, so FindByOperation can read back.
	Invoke(ctx context.Context, operation string, params json.RawMessage, operationID string) (Result, error)
	// FindByOperation looks for the effect of a previous attempt of operationID.
	FindByOperation(ctx context.Context, operation string, params json.RawMessage, operationID string) (*Result, error)
	// ReadOnly reports whether an operation has no side effects.
	ReadOnly(operation string) bool
}