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 FileEvent struct {
	event.BaseEvent

	// The operation type (promote/delete)
	Operation FileOperation `json:"operation"`
	// The meta type (uploaded_file/richtext/markdown)
	MetaType MetaType `json:"metaType"`
	// The file key (promoted key for promote, original key for delete)
	FileKey string `json:"fileKey"`
	// Parsed attributes from the meta tag
	Attrs map[string]string `json:"attrs,omitempty"`
}

type FileOperation 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 MetaType string

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 Promoter[T any] interface {
	// Promote handles file promotion and cleanup based on the scenario:
	// - newModel != nil && oldModel == nil: Create (promote new files)
	// - newModel != nil && oldModel != nil: Update (promote new files + cleanup replaced files)
	// - newModel == nil && oldModel != nil: Delete (cleanup all files)
	Promote(ctx context.Context, newModel, oldModel *T) 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 Service interface {
	// 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 multistep 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 StatObjectOptions struct {
	// Key is the unique identifier of the object
	Key string
}