feat: codegen

Introduce codegen tool like we have in other SDKs to ensure we
can keep the SDK up-to-date with latest changes in our APIs
and cover all of the APIs availabel to developers.

The setup is just the same as for sumup-py or sumup-go.
For now, we are keeping the implementation as similar to the
previous version. Once there are breaking changes we might bump
the SDK to v2.

Author: matoous

.envrc

@@ -0,0 +1,2 @@
+export SUMUP_API_KEY="sup_sk_xlfTfAqFclXWxsx0LLTdS7UP927zXdV8q"
+export SUMUP_MERCHANT_CODE="MCZHMYCM"

.github/dependabot.yml

@@ -4,9 +4,14 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
-    open-pull-requests-limit: 3
+    open-pull-requests-limit: 5
   - package-ecosystem: "composer"
     directory: "/"
     schedule:
       interval: "weekly"
-    open-pull-requests-limit: 3
+    open-pull-requests-limit: 5
+  - package-ecosystem: "gomod"
+    directory: "/codegen"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

.github/workflows/codegen.yaml

@@ -0,0 +1,55 @@
+name: Codegen CI
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - "codegen/**"
+      - ".github/workflows/codegen.yaml"
+  pull_request:
+    branches:
+      - master
+    paths:
+      - "codegen/**"
+      - ".github/workflows/codegen.yaml"
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    working-directory: ./codegen
+
+env:
+  GOLANGCI_LINT_VERSION: v2.1.5
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0
+        with:
+          go-version-file: './codegen/go.mod'
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@e7fa5ac41e1cf5b7d48e45e42232ce7ada589601 # v9.1.0
+        with:
+          version: ${{ env.GOLANGCI_LINT_VERSION }}
+          working-directory: ./codegen
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - uses: actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c # v6.1.0
+        with:
+          go-version-file: './codegen/go.mod'
+
+      - name: Run tests
+        run: go test ./...

Makefile

@@ -21,3 +21,7 @@ fmtcheck: vendor ## Check code formatting
 .PHONY: test
 test: vendor ## Run PHPUnit test suite
 	composer test
+
+.PHONY: generate
+generate: ## Generate SDK from the local OpenAPI specs
+	cd codegen && go run ./... generate ../openapi.yaml ../src

codegen/README.md

@@ -0,0 +1,15 @@
+<div align="center">
+
+# sumup-php codegen
+
+A tiny OpenAPI specs to SDK generator for [sumup-ecom-php-sdk](https://github.com/sumup/sumup-ecom-php-sdk).
+
+</div>
+
+## Quickstart
+
+Generate the SDK using:
+
+```sh
+go run ./... generate ./openapi.yaml ./build
+```

codegen/generate.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/pb33f/libopenapi"
+	"github.com/urfave/cli/v2"
+
+	"github.com/sumup/sumup-ecom-php-sdk/codegen/pkg/generator"
+)
+
+func Generate() *cli.Command {
+	var (
+		out string
+	)
+
+	return &cli.Command{
+		Name:  "generate",
+		Usage: "Generate the PHP SDK",
+		Args:  true,
+		Action: func(c *cli.Context) error {
+			if !c.Args().Present() {
+				return fmt.Errorf("empty argument, path to openapi specs expected")
+			}
+
+			specPath := c.Args().First()
+
+			if err := os.MkdirAll(out, os.ModePerm); err != nil {
+				return fmt.Errorf("create output directory %q: %w", out, err)
+			}
+
+			spec, err := os.ReadFile(specPath)
+			if err != nil {
+				return fmt.Errorf("read specs: %w", err)
+			}
+
+			doc, err := libopenapi.NewDocument(spec)
+			if err != nil {
+				return fmt.Errorf("load openapi document: %w", err)
+			}
+
+			model, err := doc.BuildV3Model()
+			if err != nil {
+				return fmt.Errorf("build openapi v3 model: %w", err)
+			}
+
+			g := generator.New(generator.Config{
+				Out: out,
+			})
+
+			if err := g.Load(&model.Model); err != nil {
+				return fmt.Errorf("load specs: %w", err)
+			}
+
+			if err := g.Build(); err != nil {
+				return fmt.Errorf("build sdk: %w", err)
+			}
+
+			return nil
+		},
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:        "out",
+				Aliases:     []string{"o"},
+				Usage:       "path of the output directory",
+				Required:    false,
+				Destination: &out,
+				Value:       "../src/",
+			},
+		},
+	}
+}

codegen/go.mod

@@ -0,0 +1,21 @@
+module github.com/sumup/sumup-ecom-php-sdk/codegen
+
+go 1.24.7
+
+require (
+	github.com/lmittmann/tint v1.1.2
+	github.com/pb33f/libopenapi v0.28.1
+	github.com/urfave/cli/v2 v2.27.7
+)
+
+require (
+	github.com/bahlo/generic-list-go v0.2.0 // indirect
+	github.com/buger/jsonparser v1.1.1 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
+	github.com/iancoleman/strcase v0.3.0 // indirect
+	github.com/pb33f/jsonpath v0.1.2 // indirect
+	github.com/pb33f/ordered-map/v2 v2.3.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
+	github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 // indirect
+	go.yaml.in/yaml/v4 v4.0.0-rc.2 // indirect
+)

codegen/go.sum

@@ -0,0 +1,32 @@
+github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
+github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
+github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs=
+github.com/buger/jsonparser v1.1.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
+github.com/cpuguy83/go-md2man/v2 v2.0.7 h1:zbFlGlXEAKlwXpmvle3d8Oe3YnkKIK4xSRTd3sHPnBo=
+github.com/cpuguy83/go-md2man/v2 v2.0.7/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/iancoleman/strcase v0.3.0 h1:nTXanmYxhfFAMjZL34Ov6gkzEsSJZ5DbhxWjvSASxEI=
+github.com/iancoleman/strcase v0.3.0/go.mod h1:iwCmte+B7n89clKwxIoIXy/HfoL7AsD47ZCWhYzw7ho=
+github.com/lmittmann/tint v1.1.2 h1:2CQzrL6rslrsyjqLDwD11bZ5OpLBPU+g3G/r5LSfS8w=
+github.com/lmittmann/tint v1.1.2/go.mod h1:HIS3gSy7qNwGCj+5oRjAutErFBl4BzdQP6cJZ0NfMwE=
+github.com/pb33f/jsonpath v0.1.2 h1:PlqXjEyecMqoYJupLxYeClCGWEpAFnh4pmzgspbXDPI=
+github.com/pb33f/jsonpath v0.1.2/go.mod h1:TtKnUnfqZm48q7a56DxB3WtL3ipkVtukMKGKxaR/uXU=
+github.com/pb33f/libopenapi v0.28.1 h1:vqE1Q08F6ohABsyKcK8kX7HYkR/+sILXGwCgFzF+aOg=
+github.com/pb33f/libopenapi v0.28.1/go.mod h1:mHMHA3ZKSZDTInNAuUtqkHlKLIjPm2HN1vgsGR57afc=
+github.com/pb33f/ordered-map/v2 v2.3.0 h1:k2OhVEQkhTCQMhAicQ3Z6iInzoZNQ7L9MVomwKBZ5WQ=
+github.com/pb33f/ordered-map/v2 v2.3.0/go.mod h1:oe5ue+6ZNhy7QN9cPZvPA23Hx0vMHnNVeMg4fGdCANw=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/urfave/cli/v2 v2.27.7 h1:bH59vdhbjLv3LAvIu6gd0usJHgoTTPhCFib8qqOwXYU=
+github.com/urfave/cli/v2 v2.27.7/go.mod h1:CyNAG/xg+iAOg0N4MPGZqVmv2rCoP267496AOXUZjA4=
+github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 h1:gEOO8jv9F4OT7lGCjxCBTO/36wtF6j2nSip77qHd4x4=
+github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1/go.mod h1:Ohn+xnUBiLI6FVj/9LpzZWtj1/D6lUovWYBkxHVV3aM=
+go.yaml.in/yaml/v4 v4.0.0-rc.2 h1:/FrI8D64VSr4HtGIlUtlFMGsm7H7pWTbj6vOLVZcA6s=
+go.yaml.in/yaml/v4 v4.0.0-rc.2/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

codegen/main.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+
+	"github.com/lmittmann/tint"
+	"github.com/urfave/cli/v2"
+)
+
+func main() {
+	if err := App().Run(os.Args); err != nil {
+		fmt.Fprintf(os.Stderr, "program exited: %v", err)
+		os.Exit(1)
+	}
+}
+
+func App() *cli.App {
+	return &cli.App{
+		Name:           "codegen",
+		Usage:          "sumup-php generator.",
+		DefaultCommand: "generate",
+		Before: func(ctx *cli.Context) error {
+			logger := slog.New(tint.NewHandler(os.Stderr, nil))
+			slog.SetDefault(logger)
+			return nil
+		},
+		Commands: []*cli.Command{
+			Generate(),
+		},
+	}
+}

codegen/pkg/extension/extension.go

@@ -0,0 +1,34 @@
+package extension
+
+import (
+	"github.com/pb33f/libopenapi/orderedmap"
+	"go.yaml.in/yaml/v4"
+)
+
+// Get extracts extension attributes from extensions.
+func Get[T any](ext *orderedmap.Map[string, *yaml.Node], key string) (T, bool) {
+	var empty T
+	if ext == nil {
+		return empty, false
+	}
+
+	if raw, ok := ext.Get(key); ok {
+		var v T
+		if err := raw.Decode(&v); err != nil {
+			return empty, false
+		}
+
+		return v, true
+	}
+
+	return empty, false
+}
+
+// GetOrDefault extracts extension attributes from extensions, returning def as default.
+func GetOrDefault[T any](ext *orderedmap.Map[string, *yaml.Node], key string, def T) T {
+	if val, ok := Get[T](ext, key); ok {
+		return val
+	}
+
+	return def
+}