awss3

type Adapter struct {
	Client Client
}

type Auth struct {
	// AccessKey is the access key to authenticate with the AWS.
	AccessKey string

	// SecretKey is the secret key to authenticate with the AWS.
	SecretKey string

	// Region is the AWS region to query.
	Region string
}

type Client interface {
	GetPage(ctx context.Context, request *Request) (*Response, *framework.Error)
}

type Config struct {
	// Common configuration
	*config.CommonConfig

	// Region is the AWS region to query.
	Region string `json:"region"`

	// Bucket is the AWS S3 bucket containing the files with entity data.
	Bucket string `json:"bucket"`

	// Prefix is the prefix of the path containing the files with entity data.
	Prefix string `json:"prefix"`

	// FileType is the extension of the files containing the entity data.
	// This defaults to "csv".
	FileType *string `json:"fileType,omitempty"`
}

type Datasource struct {
	Client                   *http.Client
	AWSConfig                *aws.Config
	MaxCSVRowSizeBytes       int64
	MaxBytesToProcessPerPage int64
}

type Request struct {
	Auth

	// Bucket is the AWS S3 bucket containing the files with entity data.
	Bucket string

	// PathPrefix is the prefix of the path containing the files with entity data.
	PathPrefix string

	// FileType is the extension of the files containing the entity data.
	FileType string

	// PageSize is the maximum number of objects to return from the entity.
	PageSize int64

	// EntityExternalID is the external ID of the entity.
	// The external ID should match the file name.
	EntityExternalID string

	// Cursor identifies the first object of the page to return, as returned by
	// the last request for the entity.
	// nil in the request for the first page.
	Cursor *S3Cursor

	// RequestTimeoutSeconds is the timeout duration for requests made to datasources.
	// This should be set to the number of seconds to wait before timing out.
	RequestTimeoutSeconds int

	// Ordered is a boolean that indicates whether the results should be ordered.
	Ordered bool

	// AttributeConfig is the list of attributes requested by the datasource.
	AttributeConfig []*framework.AttributeConfig
}

type Response struct {
	// StatusCode is an HTTP status code.
	StatusCode int

	// RetryAfterHeader is the Retry-After response HTTP header, if set.
	RetryAfterHeader string

	// Objects is the list of items returned by the datasource.
	// May be empty.
	Objects []map[string]any

	// NextCursor is the cursor that identifies the first object of the next page.
	// nil if this is the last page in this full sync.
	NextCursor *S3Cursor
}

type S3Cursor struct {
	// Cursor is the byte position offset in the file where the next S3 fetch should start.
	Cursor *int64 `json:"cursor,omitempty"`

	// Headers contains the parsed CSV headers from the first page.
	// Cached to avoid re-fetching headers on subsequent pages.
	Headers []string `json:"headers,omitempty"`

	// Remainder contains unprocessed bytes from the previous fetch.
	// These bytes are prepended to the next S3 fetch to avoid data loss.
	Remainder []byte `json:"remainder,omitempty"`
}

type S3Handler struct {
	Client *s3.Client
}