datasets

type Client struct {
	Datasets    DatasetClient
	Collections CollectionClient
	Datapoints  DatapointClient
}

type ClientOption func(*clientConfig)

type Collection struct {
	// ID is the unique identifier of the collection.
	ID uuid.UUID
	// Name is the name of the collection.
	Name string
	// Availability is the time interval for which data is available.
	Availability *query.TimeInterval
	// Count is the number of datapoints in the collection.
	Count uint64
}

type CollectionClient interface {
	// Create creates a new collection in the dataset with the given name.
	Create(ctx context.Context, datasetID uuid.UUID, name string) (*Collection, error)

	// Get returns a collection by its name.
	Get(ctx context.Context, datasetID uuid.UUID, name string) (*Collection, error)

	// GetOrCreate returns a collection by its name, creating it if it does not exist.
	GetOrCreate(ctx context.Context, datasetID uuid.UUID, name string) (*Collection, error)

	// Delete deletes a collection by its id.
	Delete(ctx context.Context, datasetID uuid.UUID, collectionID uuid.UUID) error

	// List returns a list of all available collections in the dataset.
	List(ctx context.Context, datasetID uuid.UUID) ([]*Collection, error)
}

type CollectionService interface {
	CreateCollection(ctx context.Context, datasetID uuid.UUID, collectionName string) (*datasetsv1.CollectionInfo, error)
	GetCollectionByName(ctx context.Context, datasetID uuid.UUID, collectionName string) (*datasetsv1.CollectionInfo, error)
	DeleteCollection(ctx context.Context, datasetID uuid.UUID, collectionID uuid.UUID) error
	ListCollections(ctx context.Context, datasetID uuid.UUID) (*datasetsv1.CollectionInfos, error)
}

type DataAccessService interface {
	Query(ctx context.Context, collectionIDs []uuid.UUID, filters *datasetsv1.QueryFilters, page *tileboxv1.Pagination, skipData bool) (*datasetsv1.QueryResultPage, error)
	QueryByID(ctx context.Context, collectionIDs []uuid.UUID, datapointID uuid.UUID, skipData bool) (*datasetsv1.Any, error)
}

type DataIngestionService interface {
	Ingest(ctx context.Context, collectionID uuid.UUID, datapoints [][]byte, allowExisting bool) (*datasetsv1.IngestResponse, error)
	Delete(ctx context.Context, collectionID uuid.UUID, datapointIDs []uuid.UUID) (*datasetsv1.DeleteResponse, error)
}

type DatapointClient interface {
	// GetInto get a single datapoint by its ID from one or more collections of the same dataset into a proto.Message.
	//
	// Options:
	//   - WithSkipData: can be used to skip the actual data, only returning required datapoint fields. (Optional)
	//
	// Example usage:
	//
	//	var datapoint v1.Sentinel1Sar
	//	err = client.Datapoints.GetInto(ctx, collectionIDs, datapointID, &datapoint)
	GetInto(ctx context.Context, collectionIDs []uuid.UUID, datapointID uuid.UUID, datapoint proto.Message, options ...QueryOption) error

	// Query datapoints from one or more collections of the same dataset.
	//
	// Options:
	//   - WithTemporalExtent: specifies the time or data point interval for which data should be loaded. (Required)
	//   - WithSpatialExtent: specifies the spatial extent for which data should be loaded. (Optional)
	//   - WithSkipData: can be used to skip the actual data when loading datapoints, only returning required datapoint fields. (Optional)
	//
	// The datapoints are lazily loaded and returned as a sequence of bytes.
	// The output sequence can be transformed into a proto.Message using CollectAs / As.
	//
	// Example usage:
	//
	//	for datapointBytes, err := range client.Datapoints.Query(ctx, collectionIDs, WithTemporalExtent(timeInterval), WithSpatialExtent(geometry)) {
	//	  if err != nil {
	//	    // handle error
	//	  }
	//	  datapoint := &v1.Sentinel1Sar{}
	//	  err = proto.Unmarshal(datapointBytes, datapoint)
	//	  if err != nil {
	//	    // handle unmarshal error
	//	  }
	//	  // do something with the datapoint
	//	}
	//
	// Documentation: https://docs.tilebox.com/datasets/query
	Query(ctx context.Context, collectionIDs []uuid.UUID, options ...QueryOption) iter.Seq2[[]byte, error]

	// QueryInto queries datapoints from one or more collections of the same dataset into a slice of datapoints of a
	// compatible proto.Message type.
	//
	// QueryInto is a convenience function for Query, when no manual pagination or custom iteration is required.
	//
	// Example usage:
	//
	//	var datapoints []*v1.Sentinel1Sar
	//	err := client.Datapoints.QueryInto(ctx, collectionIDs, &datapoints, WithTemporalExtent(timeInterval))
	QueryInto(ctx context.Context, collectionIDs []uuid.UUID, datapoints any, options ...QueryOption) error

	// Ingest datapoints into a collection.
	//
	// data is a list of datapoints to ingest that should be created using Datapoints.
	//
	// allowExisting specifies whether to allow existing datapoints as part of the request. If true, datapoints that already
	// exist will be ignored, and the number of such existing datapoints will be returned in the response. If false, any
	// datapoints that already exist will result in an error. Setting this to true is useful for achieving idempotency (e.g.
	// allowing re-ingestion of datapoints that have already been ingested in the past).
	Ingest(ctx context.Context, collectionID uuid.UUID, datapoints any, allowExisting bool) (*IngestResponse, error)

	// Delete datapoints from a collection.
	//
	// The datapoints are identified by their IDs.
	//
	// Returns the number of deleted datapoints.
	Delete(ctx context.Context, collectionID uuid.UUID, datapoints any) (int64, error)

	// DeleteIDs deletes datapoints from a collection by their IDs.
	//
	// Returns the number of deleted datapoints.
	DeleteIDs(ctx context.Context, collectionID uuid.UUID, datapointIDs []uuid.UUID) (int64, error)
}

type Dataset struct {
	// ID is the unique identifier of the dataset.
	ID uuid.UUID
	// Type is the type of the dataset.
	Type *datasetsv1.AnnotatedType
	// Name is the name of the dataset.
	Name string
	// Description is a short description of the dataset.
	Description string
	// Slug is the unique slug of the dataset.
	Slug string
}

type DatasetClient interface {
	// Get returns a dataset by its slug, e.g. "open_data.copernicus.sentinel1_sar".
	Get(ctx context.Context, slug string) (*Dataset, error)

	// List returns a list of all available datasets.
	List(ctx context.Context) ([]*Dataset, error)
}

type DatasetService interface {
	GetDataset(ctx context.Context, slug string) (*datasetsv1.Dataset, error)
	ListDatasets(ctx context.Context) (*datasetsv1.ListDatasetsResponse, error)
}

type IngestResponse struct {
	// NumCreated is the number of datapoints that were created.
	NumCreated int64
	// NumExisting is the number of datapoints that were ignored because they already existed.
	NumExisting int64
	// DatapointIDs is the list of all the datapoints IDs in the same order as the datapoints in the request.
	DatapointIDs []uuid.UUID
}

type QueryOption func(*queryOptions)