feat(pdfengines): add watermark and stamp feature

pkg/gotenberg/mocks.go

@@ -57,6 +57,8 @@ type PdfEngineMock struct {
 	EncryptMock        func(ctx context.Context, logger *zap.Logger, inputPath, userPassword, ownerPassword string) error
 	EmbedFilesMock     func(ctx context.Context, logger *zap.Logger, filePaths []string, inputPath string) error
 	WriteBookmarksMock func(ctx context.Context, logger *zap.Logger, inputPath string, bookmarks []Bookmark) error
+	WatermarkMock      func(ctx context.Context, logger *zap.Logger, inputPath string, stamp Stamp) error
+	StampMock          func(ctx context.Context, logger *zap.Logger, inputPath string, stamp Stamp) error
 }
 
 func (engine *PdfEngineMock) Merge(ctx context.Context, logger *zap.Logger, inputPaths []string, outputPath string) error {
@@ -103,6 +105,14 @@ func (engine *PdfEngineMock) WriteBookmarks(ctx context.Context, logger *zap.Log
 	return engine.WriteBookmarksMock(ctx, logger, inputPath, bookmarks)
 }
 
+func (engine *PdfEngineMock) Watermark(ctx context.Context, logger *zap.Logger, inputPath string, stamp Stamp) error {
+	return engine.WatermarkMock(ctx, logger, inputPath, stamp)
+}
+
+func (engine *PdfEngineMock) Stamp(ctx context.Context, logger *zap.Logger, inputPath string, stamp Stamp) error {
+	return engine.StampMock(ctx, logger, inputPath, stamp)
+}
+
 // PdfEngineProviderMock is a mock for the [PdfEngineProvider] interface.
 type PdfEngineProviderMock struct {
 	PdfEngineMock func() (PdfEngine, error)

pkg/gotenberg/pdfengine.go

@@ -28,6 +28,10 @@ var (
 	// ErrPdfEncryptionNotSupported is returned when encryption
 	// is not supported by the PDF engine.
 	ErrPdfEncryptionNotSupported = errors.New("encryption not supported")
+
+	// ErrPdfStampSourceNotSupported is returned when a stamp source type
+	// is not supported by the PDF engine.
+	ErrPdfStampSourceNotSupported = errors.New("stamp source not supported")
 )
 
 // PdfEngineInvalidArgsError represents an error returned by a PDF engine when
@@ -49,6 +53,33 @@ func NewPdfEngineInvalidArgs(engine, msg string) error {
 	return &PdfEngineInvalidArgsError{engine, msg}
 }
 
+const (
+	// StampSourceText represents a text-based stamp source.
+	StampSourceText string = "text"
+
+	// StampSourceImage represents an image-based stamp source.
+	StampSourceImage string = "image"
+
+	// StampSourcePDF represents a PDF-based stamp source.
+	StampSourcePDF string = "pdf"
+)
+
+// Stamp gathers the data required to apply a watermark or stamp to a PDF.
+type Stamp struct {
+	// Source is one of "text", "image", or "pdf".
+	Source string
+
+	// Expression is the text content (for text source) or file path (for
+	// image/pdf source).
+	Expression string
+
+	// Pages is the optional page range to apply the stamp to.
+	Pages string
+
+	// Options holds engine-specific styling options.
+	Options map[string]string
+}
+
 const (
 	// SplitModeIntervals represents a mode where a PDF is split at specific
 	// intervals.
@@ -166,6 +197,12 @@ type PdfEngine interface {
 	// without modifying the main PDF content.
 	// TODO: attachments instead? Rename the route?
 	EmbedFiles(ctx context.Context, logger *zap.Logger, filePaths []string, inputPath string) error
+
+	// Watermark applies a watermark (behind page content) to a PDF file.
+	Watermark(ctx context.Context, logger *zap.Logger, inputPath string, stamp Stamp) error
+
+	// Stamp applies a stamp (on top of page content) to a PDF file.
+	Stamp(ctx context.Context, logger *zap.Logger, inputPath string, stamp Stamp) error
 }
 
 // PdfEngineProvider offers an interface to instantiate a [PdfEngine].