[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,57 @@ 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"
+	BatchStatusFailure BatchStatus = "failure"
+	BatchStatusPartial BatchStatus = "partial"
+)
+
+// BatchWriteType specifies the intended operation type within a batch modification.
+type BatchWriteType string
+
+const (
+	BatchWriteTypeCreate BatchWriteType = "create"
+	BatchWriteTypeUpdate BatchWriteType = "update"
+)
+
+// 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
+	// Records contains the collection of record payloads to be written.
+	Records []any
+}
+
+// BatchWriteResult aggregates the outcome of a synchronous batch write operation.
+// It reports an overall batch status, any top-level errors, and the per-record
+// results for each record processed in the batch.
+type BatchWriteResult struct {
+	// Status summarizes the batch outcome (success, failure, or partial).
+	Status BatchStatus
+	// Errors lists top-level errors that are not tied to specific records.
+	// While errors that are specific to certain records are found in Results[i].Errors
+	Errors []any
+	// Results contains the detailed outcomes for each record in the batch.
+	Results []WriteResult
+	// SuccessCount is the number of successfully written records.
+	SuccessCount int `json:"successCount"`
+	// FailureCount is the number of failed records.
+	FailureCount int `json:"failureCount"`
+}
+
 // 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,21 @@ func (p DeleteParams) ValidateParams() error {
 
 	return nil
 }
+
+var ErrUnknownBatchWriteType = errors.New("unknown batch write type")
+
+func (p BatchWriteParam) ValidateParams() error {
+	if len(p.ObjectName) == 0 {
+		return ErrMissingObjects
+	}
+
+	if p.Type == BatchWriteTypeCreate || p.Type == BatchWriteTypeUpdate {
+		return ErrUnknownBatchWriteType
+	}
+
+	if len(p.Records) == 0 {
+		return ErrMissingRecordData
+	}
+
+	return nil
+}

connectors.go

@@ -69,6 +69,23 @@ type DeleteConnector interface {
 	Delete(ctx context.Context, params DeleteParams) (*DeleteResult, error)
 }
 
+// BatchWriteConnector provides synchronous operations for writing multiple records in a single request.
+// It serves the same purpose as WriteConnector 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 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)
+}
+
 // ObjectMetadataConnector is an interface that extends the Connector interface with
 // the ability to list object metadata.
 type ObjectMetadataConnector interface {