storage

type CopyObjectOptions struct {
	// SourceKey is the identifier of the source object
	SourceKey string
	// DestKey is the identifier for the copied object
	DestKey string
}

type DeleteObjectOptions struct {
	// Key is the unique identifier of the object to delete
	Key string
}

type DeleteObjectsOptions struct {
	// Keys is the list of object identifiers to delete
	Keys []string
}

type GetObjectOptions struct {
	// Key is the unique identifier of the object
	Key string
}

type ListObjectsOptions struct {
	// Prefix filters objects by key prefix
	Prefix string
	// Recursive determines whether to list objects recursively
	Recursive bool
	// MaxKeys limits the maximum number of objects to return
	MaxKeys int
}

type MoveObjectOptions struct {
	CopyObjectOptions
}

type ObjectInfo struct {
	// Bucket is the name of the storage bucket
	Bucket string `json:"bucket"`

	// Key is the unique identifier of the object within the bucket
	Key string `json:"key"`

	// ETag is the entity tag, typically an MD5 hash used for versioning and cache validation
	ETag string `json:"eTag"`

	// Size is the object size in bytes
	Size int64 `json:"size"`

	// ContentType is the MIME type of the object
	ContentType string `json:"contentType"`

	// LastModified is the timestamp when the object was last modified
	LastModified time.Time `json:"lastModified"`

	// Metadata contains custom key-value pairs associated with the object
	Metadata map[string]string `json:"metadata,omitempty"`
}

type PresignedURLOptions struct {
	// Key is the unique identifier of the object
	Key string
	// Expires specifies how long the presigned URL remains valid
	Expires time.Duration
	// Method specifies the HTTP method (GET for download, PUT for upload)
	Method string
}

type Provider interface {
	// Setup initializes the storage provider (e.g., creating buckets, directories).
	// This method should ONLY be called during application startup and MUST NOT be called at runtime.
	Setup(ctx context.Context) error

	// PutObject uploads an object to storage
	PutObject(ctx context.Context, opts PutObjectOptions) (*ObjectInfo, error)
	// GetObject retrieves an object from storage
	GetObject(ctx context.Context, opts GetObjectOptions) (io.ReadCloser, error)
	// DeleteObject deletes a single object from storage
	DeleteObject(ctx context.Context, opts DeleteObjectOptions) error
	// DeleteObjects deletes multiple objects from storage in a batch operation
	DeleteObjects(ctx context.Context, opts DeleteObjectsOptions) error
	// ListObjects lists objects in a bucket with optional filtering
	ListObjects(ctx context.Context, opts ListObjectsOptions) ([]ObjectInfo, error)
	// GetPresignedURL generates a presigned URL for temporary access to an object
	GetPresignedURL(ctx context.Context, opts PresignedURLOptions) (string, error)
	// CopyObject copies an object from source to destination
	CopyObject(ctx context.Context, opts CopyObjectOptions) (*ObjectInfo, error)
	// MoveObject moves an object from source to destination (implemented as Copy + Delete)
	MoveObject(ctx context.Context, opts MoveObjectOptions) (*ObjectInfo, error)
	// StatObject retrieves metadata information about an object
	StatObject(ctx context.Context, opts StatObjectOptions) (*ObjectInfo, error)

	// PromoteObject moves an object from temporary storage (temp/ prefix) to permanent storage.
	// It removes the "temp/" prefix from the object key, effectively promoting a temporary upload
	// to a permanent file. This is useful for handling multi-step upload workflows where files
	// are initially uploaded to temp/ and only moved to permanent storage after business logic commits.
	// If the key does not start with "temp/", this method does nothing and returns nil.
	PromoteObject(ctx context.Context, tempKey string) (*ObjectInfo, error)
}

type PutObjectOptions struct {
	// Key is the unique identifier for the object
	Key string
	// Reader provides the object data to upload
	Reader io.Reader
	// Size is the size of the data in bytes (-1 if unknown)
	Size int64
	// ContentType specifies the MIME type of the object
	ContentType string
	// Metadata contains custom key-value pairs to store with the object
	Metadata map[string]string
}

type StatObjectOptions struct {
	// Key is the unique identifier of the object
	Key string
}