connectors

type AuthMetadataConnector interface {
	Connector

	// GetPostAuthInfo returns authentication metadata.
	GetPostAuthInfo(ctx context.Context) (*common.PostAuthInfo, error)
}

type BatchRecordReaderConnector interface {
	Connector

	// GetRecordsByIds fetches full records from the provider for a specific set of IDs.
	//
	// This method is primarily used during webhook processing to enrich events that
	// require fetching the current full state of records from the provider API.
	// In that lifecycle, webhook payloads often contain only partial data, making
	// an explicit read necessary to produce complete, descriptive ReadResultRow values.
	//
	// More generally, this method represents a targeted read operation: it allows
	// callers to retrieve a known set of records by ID without performing a full
	// collection read. This is useful in non-webhook lifecycles as well, such as
	// enriching read results with associated sub-objects, resolving references to
	// related objects, or performing joined reads where supported by the provider.
	//
	// Compared to Read (which lists collections of records), GetRecordsByIds is a
	// singular-by-identity read that operates over multiple explicit IDs.
	//
	// The connector should:
	//   - Fetch only the specified recordIds
	//   - Respect requested fields and associations when supported by the provider
	//   - Return provider responses translated into ReadResultRow
	GetRecordsByIds(
		ctx context.Context,
		objectName string,
		recordIds []string,
		fields []string,
		associations []string,
	) ([]common.ReadResultRow, error)
}

type BatchStatus = common.BatchStatus

type BatchWriteConnector interface {
	Connector

	// BatchWrite performs a batch create, update, or upsert operation.
	// Each record in params.Records is processed according to params.Type.
	// The returned BatchWriteResult includes both per-record outcomes and the aggregate batch status.
	BatchWrite(ctx context.Context, params *common.BatchWriteParam) (*common.BatchWriteResult, error)
}

type BatchWriteParam = common.BatchWriteParam

type BatchWriteResult = common.BatchWriteResult

type ConfigurationConnector interface {
	Connector

	DefaultPageSize() int
}

type Connector interface {
	fmt.Stringer

	// JSONHTTPClient returns the underlying JSON HTTP client. This is useful for
	// testing, or for calling methods that aren't exposed by the Connector
	// interface directly. Authentication and token refreshes will be handled automatically.
	JSONHTTPClient() *common.JSONHTTPClient

	// HTTPClient returns the underlying HTTP client. This is useful for proxy requests.
	HTTPClient() *common.HTTPClient

	// Provider returns the connector provider.
	Provider() providers.Provider
}

type DeleteConnector interface {
	Connector

	Delete(ctx context.Context, params DeleteParams) (*DeleteResult, error)
}

type DeleteMetadataConnector interface {
	Connector

	DeleteMetadata(ctx context.Context, params *common.DeleteMetadataParams) (*common.DeleteMetadataResult, error)
}

type DeleteParams = common.DeleteParams

type DeleteResult = common.DeleteResult

type ErrorWithStatus = common.HTTPError //nolint:errname

type ListObjectMetadataResult = common.ListObjectMetadataResult

type ObjectMetadataConnector interface {
	Connector

	ListObjectMetadata(ctx context.Context, objectNames []string) (*ListObjectMetadataResult, error)
}

type ProxyConfig struct {
	// URL is used for proxying requests.
	URL string
}

type ProxyConnector interface {
	Connector

	// ProxyConfig returns the general proxy configuration for the provider.
	//
	// This represents the base proxy used for the provider.
	//
	// Returns common.ErrProxyNotApplicable if proxying is not supported.
	ProxyConfig() (*ProxyConfig, error)

	// ProxyModuleConfig returns the module-specific proxy configuration.
	//
	// If the connector instance is associated with a module, the returned
	// configuration may include module-specific pathing, host, or routing.
	//
	// If the instance is not associated with a module, this MUST return the same
	// configuration as ProxyConfig().
	//
	// Returns common.ErrProxyNotApplicable if proxying is not supported.
	ProxyModuleConfig() (*ProxyConfig, error)
}

type ReadConnector interface {
	Connector

	// Read reads a page of data from the connector. This can be called multiple
	// times to read all the data. The caller is responsible for paging, by
	// passing the NextPage value correctly, and by terminating the loop when
	// Done is true. The caller is also responsible for handling errors.
	// Authentication corner cases are handled internally, but all other errors
	// are returned to the caller.
	Read(ctx context.Context, params ReadParams) (*ReadResult, error)
}

type ReadParams = common.ReadParams

type ReadResult = common.ReadResult

type RecordCountConnector interface {
	Connector

	// GetRecordCount returns the count of records for the given object and time range.
	//
	// Parameters:
	//   - ctx: context for the operation
	//   - params: parameters specifying the object name and optional time range
	//
	// Returns:
	//   - *RecordCountResult: the result containing the count
	//   - error: any error that occurred while fetching the count
	GetRecordCount(ctx context.Context, params *common.RecordCountParams) (*common.RecordCountResult, error)
}

type RecordCountParams = common.RecordCountParams

type RecordCountResult = common.RecordCountResult

type RegisterSubscribeConnector interface {
	SubscribeConnector

	// Register performs a provider-specific registration required to enable
	// webhook subscriptions.
	//
	// This is typically a one-time operation per installation that
	// may create shared infrastructure used by all subsequent subscriptions.
	Register(
		ctx context.Context,
		params common.SubscriptionRegistrationParams,
	) (*common.RegistrationResult, error)

	// DeleteRegistration removes a previously created registration from the provider.
	//
	// This method is called when the framework determines that the registration
	// is no longer needed (for example, when all subscriptions have been removed)
	DeleteRegistration(
		ctx context.Context,
		previousResult common.RegistrationResult,
	) error

	// EmptyRegistrationParams returns an empty, provider-specific common.SubscriptionRegistrationParams instance.
	//
	// The returned common.SubscriptionRegistrationParams has the Request field (of type any)
	// initialized to an empty value appropriate for the provider.
	EmptyRegistrationParams() *common.SubscriptionRegistrationParams

	// EmptyRegistrationResult returns an empty, provider-specific common.RegistrationResult instance.
	//
	// The returned common.RegistrationResult has the Result field (of type any)
	// initialized to an empty value appropriate for storing the provider's raw response.
	EmptyRegistrationResult() *common.RegistrationResult
}

type SearchConnector interface {
	Connector

	// Search searches for records in the given object and time range.
	//
	// Parameters:
	//   - ctx: context for the operation
	//   - params: parameters specifying the object name and optional time range
	//
	// Returns:
	//   - *SearchResult: the result containing the search results
	//   - error: any error that occurred while searching
	Search(ctx context.Context, params *common.SearchParams) (*common.SearchResult, error)
}

type SearchFilter = common.SearchFilter

type SearchParams = common.SearchParams

type SearchResult = common.SearchResult

type SubscribeConnector interface {
	WebhookVerifierConnector

	// Subscribe creates webhook subscriptions in the provider.
	//
	// SubscribeParams describe the desired subscription state in a normalized,
	// provider-agnostic format, such as subscribing to objects, certain event types,
	// or specific fields. The connector translates this configuration into
	// provider-specific API calls and returns the resulting subscription state.
	Subscribe(
		ctx context.Context,
		params common.SubscribeParams,
	) (*common.SubscriptionResult, error)

	// UpdateSubscription applies detected changes to an existing provider-side subscription.
	//
	// This method is called only after the framework detects changes in the desired
	// subscription configuration (e.g., objects or events added or removed).
	//
	// The params argument represents the new desired subscription state.
	// The previousResult contains the last known actual subscription state stored
	// by the framework.
	//
	// The connector must apply the necessary provider-specific operations to reconcile
	// the existing subscription with the desired state. The reconciliation process
	// is provider-specific.
	//
	// The returned SubscriptionResult must reflect the actual subscription state
	// after the update and will be persisted for future updates or deletion.
	UpdateSubscription(
		ctx context.Context,
		params common.SubscribeParams,
		previousResult *common.SubscriptionResult,
	) (*common.SubscriptionResult, error)

	// DeleteSubscription removes an existing provider-side subscription.
	//
	// This method is called when the framework determines that no subscription
	// lookups remain (i.e., no objects or events are left to subscribe to).
	//
	// The previousResult contains the provider-specific information needed to
	// identify and delete the subscription resources created by Subscribe or
	// UpdateSubscription.
	//
	// After this method succeeds, the provider should no longer send webhook events
	// for this subscription.
	DeleteSubscription(
		ctx context.Context,
		previousResult common.SubscriptionResult,
	) error

	// EmptySubscriptionParams returns an empty, provider-specific common.SubscribeParams instance.
	//
	// The returned common.SubscribeParams has the Request field (of type any)
	// initialized to an empty value appropriate for the provider.
	EmptySubscriptionParams() *common.SubscribeParams

	// EmptySubscriptionResult returns an empty, provider-specific common.SubscriptionResult instance.
	//
	// The returned common.SubscriptionResult has the Result field (of type any)
	// initialized to an empty value appropriate for storing the provider's raw response.
	EmptySubscriptionResult() *common.SubscriptionResult
}

type SubscriptionMaintainerConnector interface {
	SubscribeConnector

	// RunScheduledMaintenance performs provider-specific maintenance for an
	// existing subscription.
	//
	// The params argument represents the desired subscription state and is
	// typically identical to the currently active configuration.
	//
	// The previousResult contains the last known actual subscription state stored
	// by the framework and may include provider-specific identifiers, timestamps,
	// or expiration information required to renew the subscription.
	//
	// The returned SubscriptionResult must reflect the actual subscription state
	// after maintenance and will be persisted for future maintenance, updates,
	// or deletion.
	RunScheduledMaintenance(
		ctx context.Context,
		params common.SubscribeParams,
		previousResult *common.SubscriptionResult,
	) (*common.SubscriptionResult, error)
}

type URLConnector interface {
	Connector

	// GetURL returns the URL of some resource. The resource is provider-specific.
	// The URL is returned as a string, or an error is returned if the URL cannot be
	// retrieved. The precise meaning of the resource is provider-specific, and the
	// caller should consult the provider's documentation for more information.
	// The args parameter is a map of key-value pairs that can be used to customize
	// the URL. The keys and values are provider-specific, and the caller should
	// consult the provider's documentation for more information. Certain providers
	// may ignore the args parameter entirely if it's unnecessary.
	GetURL(resource string, args map[string]any) (string, error)
}

type UpsertMetadataConnector interface {
	Connector

	UpsertMetadata(ctx context.Context, params *common.UpsertMetadataParams) (*common.UpsertMetadataResult, error)
}

type WebhookVerifierConnector interface {
	Connector
	BatchRecordReaderConnector

	// VerifyWebhookMessage validates the authenticity of an incoming webhook request.
	//
	// The method should verify that the HTTP request was sent by the provider and
	// has not been tampered with. Verification is provider-specific and may rely on
	// request headers, the raw request body, the request URL, or other metadata.
	//
	// Example: verifying a webhook signature using a shared secret.
	//
	// Returning true allows webhook processing to continue.
	// Returning false indicates the request is not trusted and should be rejected.
	// An error should be returned only for unexpected verification failures.
	//
	// Parameters:
	//   - request: the raw webhook HTTP request received from the provider.
	//   - params: provider-specific and user-specific verification parameters, such as
	//     secrets or configuration needed to validate the webhook signature.
	VerifyWebhookMessage(
		ctx context.Context,
		request *common.WebhookRequest,
		params *common.VerificationParams,
	) (bool, error)
}

type WriteConnector interface {
	Connector

	Write(ctx context.Context, params WriteParams) (*WriteResult, error)
}

type WriteParams = common.WriteParams

type WriteResult = common.WriteResult

type WriteType = common.WriteType