fix(codegen): generate service accessors (#152)

Sales and Tokens have generated service files but cannot be accessed
through the PHP client. Service accessors were maintained by hand, and
Composer listed generated files individually.

Generate a service-accessor trait from the same API groups as the
services and use a directory classmap for autoloading. The hand-written
client keeps its authentication and event methods. New API groups no
longer need manual registration.

Add a new-group generator regression, exercise Sales and Tokens through
the configured client, and check in CI that regeneration leaves no
missing or stale SDK files.

Author: matoous

.github/workflows/codegen.yaml

@@ -6,6 +6,7 @@ on:
       - main
     paths:
       - "codegen/**"
+      - "src/**"
       - "openapi.json"
       - "composer.json"
       - "justfile"
@@ -15,6 +16,7 @@ on:
       - main
     paths:
       - "codegen/**"
+      - "src/**"
       - "openapi.json"
       - "composer.json"
       - "justfile"
@@ -65,3 +67,37 @@ jobs:
 
       - name: Run tests
         run: go test ./...
+
+  generated:
+    name: Generated SDK
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: './codegen/go.mod'
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2.40.0
+        with:
+          php-version: '8.2.35'
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+        working-directory: .
+
+      - name: Generate SDK
+        run: go run . generate --out ../src ../openapi.json
+
+      - name: Format generated SDK
+        run: vendor/bin/php-cs-fixer fix --using-cache=no
+        working-directory: .
+
+      - name: Ensure generated SDK is up to date
+        run: |
+          git diff --exit-code -- src
+          test -z "$(git ls-files --others --exclude-standard -- src)"
+        working-directory: .

codegen/README.md

@@ -81,4 +81,4 @@ class CheckoutRequest { /* ... */ }
 
 #### Autoloading
 
-Generated files with multiple classes and enums are added to the `classmap` in `composer.json` to ensure proper autoloading.
+Composer's `classmap` covers `src/`, including generated files with multiple classes and enums. The generator also writes `src/ServiceAccessors.php`, which provides the API group methods used by `SumUp`. Adding an API group to the specification therefore adds its client accessor and autoloading without a manual registration step.

codegen/pkg/generator/generator.go

@@ -149,11 +149,9 @@ func (g *Generator) Build() error {
 
 	slog.Info("models generated", slog.Int("tags", len(tagKeys)))
 
-	// Skip SumUp class generation to avoid breaking existing code
-	// TODO: Fix Authorization service dependency before re-enabling
-	// if err := g.writeSumUpClass(); err != nil {
-	// 	return err
-	// }
+	if err := g.writeServiceAccessors(); err != nil {
+		return err
+	}
 
 	if err := g.writeApiVersion(); err != nil {
 		return err

codegen/pkg/generator/service_accessors.go

@@ -0,0 +1,48 @@
+package generator
+
+import (
+	"bytes"
+	"fmt"
+	"maps"
+	"os"
+	"path/filepath"
+	"slices"
+
+	"github.com/iancoleman/strcase"
+)
+
+// writeServiceAccessors keeps the generated API groups separate from the hand-written client.
+func (g *Generator) writeServiceAccessors() error {
+	var services []string
+	for _, tagKey := range slices.Sorted(maps.Keys(g.operationsByTag)) {
+		if g.shouldIncludeService(tagKey, g.operationsByTag[tagKey]) {
+			services = append(services, g.displayTagName(tagKey))
+		}
+	}
+
+	var buf bytes.Buffer
+	buf.WriteString("<?php\n\n// Code generated by sumup-php/codegen. DO NOT EDIT.\nnamespace SumUp;\n\n")
+	for _, service := range services {
+		fmt.Fprintf(&buf, "use SumUp\\Services\\%s;\n", service)
+	}
+	buf.WriteString("\n/** API groups available through the SumUp client. */\ntrait ServiceAccessors\n{\n")
+	for i, service := range services {
+		if i > 0 {
+			buf.WriteString("\n")
+		}
+		buf.WriteString("    /**\n")
+		fmt.Fprintf(&buf, "     * Access the %s API endpoints.\n", service)
+		buf.WriteString("     */\n")
+		fmt.Fprintf(&buf, "    public function %s(): %s\n", strcase.ToLowerCamel(service), service)
+		buf.WriteString("    {\n")
+		fmt.Fprintf(&buf, "        return new %s($this->client, $this->resolveAccessToken());\n", service)
+		buf.WriteString("    }\n")
+	}
+	buf.WriteString("}\n")
+
+	filename := filepath.Join(g.cfg.Out, "ServiceAccessors.php")
+	if err := os.WriteFile(filename, buf.Bytes(), 0o644); err != nil {
+		return fmt.Errorf("write service accessors: %w", err)
+	}
+	return nil
+}

codegen/pkg/generator/service_accessors_test.go

@@ -0,0 +1,51 @@
+package generator
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/pb33f/libopenapi"
+)
+
+func TestGenerateServiceAccessors(t *testing.T) {
+	t.Parallel()
+	const spec = `{
+		"openapi": "3.1.0",
+		"info": {"title": "Widgets", "version": "1.0.0"},
+		"paths": {"/widgets": {"get": {
+			"tags": ["Widgets"], "operationId": "listWidgets",
+			"responses": {"204": {"description": "No widgets"}}
+		}}}
+	}`
+	doc, err := libopenapi.NewDocument([]byte(spec))
+	if err != nil {
+		t.Fatal(err)
+	}
+	model, err := doc.BuildV3Model()
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := t.TempDir()
+	g := New(Config{Out: out})
+	if err := g.Load(&model.Model); err != nil {
+		t.Fatal(err)
+	}
+	if err := g.Build(); err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(filepath.Join(out, "ServiceAccessors.php"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, snippet := range []string{
+		`use SumUp\Services\Widgets;`,
+		`public function widgets(): Widgets`,
+		`return new Widgets($this->client, $this->resolveAccessToken());`,
+	} {
+		if !strings.Contains(string(data), snippet) {
+			t.Errorf("service accessors missing %q", snippet)
+		}
+	}
+}