[ENG-2914] feat(interface): BatchWriteConnector

common/types.go

@@ -272,7 +272,7 @@ type Association struct {
 	Raw             map[string]any `json:"raw,omitempty"`
 }
 
-// WriteResult is what's returned from writing data via the Write call.
+// WriteResult represents the outcome of a single record write operation.
 type WriteResult struct {
 	// Success is true if write succeeded.
 	Success bool `json:"success"`
@@ -284,12 +284,70 @@ type WriteResult struct {
 	Data map[string]any `json:"data,omitempty"` // optional
 }
 
-// DeleteResult is what's returned from deleting data via the Delete call.
+// DeleteResult represents the outcome of a single record delete operation.
 type DeleteResult struct {
 	// Success is true if deletion succeeded.
 	Success bool `json:"success"`
 }
 
+// BatchStatus describes the aggregate outcome of a batch operation.
+type BatchStatus string
+
+const (
+	BatchStatusSuccess BatchStatus = "success"
+	BatchStatusFail    BatchStatus = "fail"
+	BatchStatusPartial BatchStatus = "partial"
+)
+
+// BatchResult aggregates the outcome of a synchronous batch operation.
+// It reports an overall batch status, any top-level errors, and the per-record
+// results for each record processed in the batch.
+//
+// [R] is the per-record result type (for example, WriteResult or DeleteResult).
+type BatchResult[R any] struct {
+	// Status summarizes the batch outcome (success, fail, or partial).
+	Status BatchStatus
+	// Errors lists top-level errors that are not tied to specific records.
+	Errors []any
+	// Results contains the detailed outcomes for each record in the batch.
+	Results []R
+}
+
+// BatchWriteType specifies the intended operation type within a batch modification.
+type BatchWriteType string // TODO maybe we should call this "BatchWriteMode"?
+
+const (
+	BatchWriteTypeCreate BatchWriteType = "create"
+	BatchWriteTypeUpdate BatchWriteType = "update"
+	BatchWriteTypeUpsert BatchWriteType = "upsert"
+)
+
+// BatchWriteParam defines the input required to execute a batch write operation.
+// It allows creating, updating, or upserting multiple records in a single request.
+type BatchWriteParam struct {
+	// ObjectName identifies the target object for the write operation.
+	ObjectName ObjectName
+	// Type defines how the records should be processed: create, update, or upsert.
+	Type BatchWriteType // TODO maybe we should call this "Mode"?
+	// Records contains the collection of record payloads to be written.
+	Records []any
+}
+
+// BatchWriteResult represents the outcome of a batch write request.
+type BatchWriteResult BatchResult[WriteResult]
+
+// BatchDeleteParam defines the input required to execute a batch delete operation.
+// It enables deleting multiple records belonging to the same object in a single request.
+type BatchDeleteParam struct {
+	// ObjectName identifies the target object for the delete operation.
+	ObjectName ObjectName
+	// RecordIDs specifies the identifiers of the records to remove.
+	RecordIDs []string
+}
+
+// BatchDeleteResult represents the outcome of a batch delete request.
+type BatchDeleteResult BatchResult[DeleteResult]
+
 // WriteMethod is signature for any HTTP method that performs write modifications.
 // Ex: Post/Put/Patch.
 type WriteMethod func(context.Context, string, any, ...Header) (*JSONHTTPResponse, error)

common/validation.go

@@ -1,6 +1,8 @@
 package common
 
-import "errors"
+import (
+	"errors"
+)
 
 var (
 	// ErrMissingObjects is returned when no objects are provided in the request.
@@ -66,3 +68,33 @@ func (p DeleteParams) ValidateParams() error {
 
 	return nil
 }
+
+var ErrUnknownBatchWriteType = errors.New("unknown batch write type") // TODO should it be "mode"?
+
+func (p BatchWriteParam) ValidateParams() error {
+	if len(p.ObjectName) == 0 {
+		return ErrMissingObjects
+	}
+
+	if p.Type == BatchWriteTypeCreate || p.Type == BatchWriteTypeUpdate || p.Type == BatchWriteTypeUpsert {
+		return ErrUnknownBatchWriteType
+	}
+
+	if len(p.Records) == 0 {
+		return ErrMissingRecordData
+	}
+
+	return nil
+}
+
+func (p BatchDeleteParam) ValidateParams() error {
+	if len(p.ObjectName) == 0 {
+		return ErrMissingObjects
+	}
+
+	if len(p.RecordIDs) == 0 {
+		return ErrMissingRecordID
+	}
+
+	return nil
+}

connectors.go

@@ -69,6 +69,24 @@ type DeleteConnector interface {
 	Delete(ctx context.Context, params DeleteParams) (*DeleteResult, error)
 }
 
+// BatchWriterConnector provides synchronous operations for writing and deleting multiple records in a single request.
+// It serves the same purpose as WriteConnector and DeleteConnector but operates
+// on collections of records instead of individual ones.
+//
+// Implementations should handle each record independently and report both
+// overall and per-record outcomes through the returned result types.
+// Errors returned from the methods represent connector-level issues such as
+// network failures or invalid authentication, not individual record failures.
+type BatchWriterConnector interface {
+	// 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)
+	// BatchDelete removes multiple records identified by params.RecordIDs.
+	// The returned BatchDeleteResult reports both overall and per-record outcomes.
+	BatchDelete(ctx context.Context, params *common.BatchDeleteParam) (*common.BatchDeleteResult, error)
+}
+
 // ObjectMetadataConnector is an interface that extends the Connector interface with
 // the ability to list object metadata.
 type ObjectMetadataConnector interface {