feat(pdfengines): inject Factur-X/ZUGFeRD XMP metadata

pkg/modules/api/formdata.go

@@ -424,6 +424,89 @@ func (form *FormData) EmbedsMetadata(target *map[string]map[string]string) *Form
 	return form
 }
 
+// FacturX parses the "facturx" form field (a JSON string) into a
+// [gotenberg.FacturX]. The "conformanceLevel" property is mandatory; the
+// "documentType", "version", and "documentFileName" properties default to
+// "INVOICE", "1.0", and "factur-x.xml" respectively. It leaves the target
+// untouched when the field is absent.
+//
+//	var facturX gotenberg.FacturX
+//
+//	ctx.FormData().FacturX(&facturX, false)
+func (form *FormData) FacturX(target *gotenberg.FacturX, mandatory bool) *FormData {
+	if form.errors != nil {
+		return form
+	}
+
+	val, ok := form.values["facturx"]
+	if !ok || len(val) == 0 || val[0] == "" {
+		if mandatory {
+			form.append(fmt.Errorf("form field '%s' is required", "facturx"))
+		}
+		return form
+	}
+
+	var parsed struct {
+		ConformanceLevel string `json:"conformanceLevel"`
+		DocumentType     string `json:"documentType"`
+		DocumentFileName string `json:"documentFileName"`
+		Version          string `json:"version"`
+	}
+
+	err := json.Unmarshal([]byte(val[0]), &parsed)
+	if err != nil {
+		form.append(fmt.Errorf("form field 'facturx' is invalid: %w", err))
+		return form
+	}
+
+	facturX := gotenberg.FacturX{
+		ConformanceLevel: parsed.ConformanceLevel,
+		DocumentType:     parsed.DocumentType,
+		DocumentFileName: parsed.DocumentFileName,
+		Version:          parsed.Version,
+	}
+
+	if facturX.DocumentType == "" {
+		facturX.DocumentType = gotenberg.FacturXDocumentTypeInvoice
+	}
+
+	if facturX.Version == "" {
+		facturX.Version = "1.0"
+	}
+
+	if facturX.DocumentFileName == "" {
+		facturX.DocumentFileName = "factur-x.xml"
+	}
+
+	switch facturX.ConformanceLevel {
+	case gotenberg.FacturXConformanceMinimum,
+		gotenberg.FacturXConformanceBasicWL,
+		gotenberg.FacturXConformanceBasic,
+		gotenberg.FacturXConformanceEN16931,
+		gotenberg.FacturXConformanceExtended,
+		gotenberg.FacturXConformanceXRechnung:
+	case "":
+		form.append(errors.New("form field 'facturx' is invalid: 'conformanceLevel' is required"))
+		return form
+	default:
+		form.append(fmt.Errorf("form field 'facturx' is invalid: unsupported 'conformanceLevel' '%s'", facturX.ConformanceLevel))
+		return form
+	}
+
+	switch facturX.DocumentType {
+	case gotenberg.FacturXDocumentTypeInvoice,
+		gotenberg.FacturXDocumentTypeOrder,
+		gotenberg.FacturXDocumentTypeOrderResponse,
+		gotenberg.FacturXDocumentTypeOrderChange:
+	default:
+		form.append(fmt.Errorf("form field 'facturx' is invalid: unsupported 'documentType' '%s'", facturX.DocumentType))
+		return form
+	}
+
+	*target = facturX
+	return form
+}
+
 // MandatoryPaths binds the absolute paths of form data files, according to a
 // list of file extensions, to a string slice variable. It populates an error
 // if there is no file for given file extensions.

pkg/modules/api/formdata_test.go

@@ -7,6 +7,8 @@ import (
 	"reflect"
 	"testing"
 	"time"
+
+	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )
 
 func TestFormData_Validate(t *testing.T) {
@@ -1783,3 +1785,111 @@ func TestFormData_Embeds(t *testing.T) {
 		t.Errorf("expected %v but got %v", expected, actual)
 	}
 }
+
+func TestFormData_FacturX(t *testing.T) {
+	for _, tc := range []struct {
+		scenario  string
+		form      *FormData
+		mandatory bool
+		expect    gotenberg.FacturX
+		expectErr bool
+	}{
+		{
+			scenario:  "key does not exist, not mandatory",
+			form:      &FormData{},
+			mandatory: false,
+			expect:    gotenberg.FacturX{},
+		},
+		{
+			scenario:  "key does not exist, mandatory",
+			form:      &FormData{},
+			mandatory: true,
+			expectErr: true,
+		},
+		{
+			scenario: "all fields provided",
+			form: &FormData{
+				values: map[string][]string{
+					"facturx": {`{"conformanceLevel":"EXTENDED","documentType":"ORDER","documentFileName":"order.xml","version":"2.0"}`},
+				},
+			},
+			expect: gotenberg.FacturX{
+				ConformanceLevel: gotenberg.FacturXConformanceExtended,
+				DocumentType:     gotenberg.FacturXDocumentTypeOrder,
+				DocumentFileName: "order.xml",
+				Version:          "2.0",
+			},
+		},
+		{
+			scenario: "only conformance level, defaults applied",
+			form: &FormData{
+				values: map[string][]string{
+					"facturx": {`{"conformanceLevel":"EN 16931"}`},
+				},
+			},
+			expect: gotenberg.FacturX{
+				ConformanceLevel: gotenberg.FacturXConformanceEN16931,
+				DocumentType:     gotenberg.FacturXDocumentTypeInvoice,
+				DocumentFileName: "factur-x.xml",
+				Version:          "1.0",
+			},
+		},
+		{
+			scenario: "invalid JSON",
+			form: &FormData{
+				values: map[string][]string{
+					"facturx": {`{not json`},
+				},
+			},
+			expectErr: true,
+		},
+		{
+			scenario: "missing conformance level",
+			form: &FormData{
+				values: map[string][]string{
+					"facturx": {`{"documentType":"INVOICE"}`},
+				},
+			},
+			expectErr: true,
+		},
+		{
+			scenario: "unsupported conformance level",
+			form: &FormData{
+				values: map[string][]string{
+					"facturx": {`{"conformanceLevel":"FOO"}`},
+				},
+			},
+			expectErr: true,
+		},
+		{
+			scenario: "unsupported document type",
+			form: &FormData{
+				values: map[string][]string{
+					"facturx": {`{"conformanceLevel":"BASIC","documentType":"RECEIPT"}`},
+				},
+			},
+			expectErr: true,
+		},
+	} {
+		t.Run(tc.scenario, func(t *testing.T) {
+			var actual gotenberg.FacturX
+
+			tc.form.FacturX(&actual, tc.mandatory)
+
+			if tc.expectErr {
+				if tc.form.errors == nil {
+					t.Error("expected an error but got none")
+				}
+				return
+			}
+
+			if tc.form.errors != nil {
+				t.Errorf("expected no error but got: %v", tc.form.errors)
+			}
+
+			if !reflect.DeepEqual(actual, tc.expect) {
+				t.Errorf("expected %+v but got %+v", tc.expect, actual)
+			}
+		})
+	}
+}