docs(events): include API descriptions in event PHPDoc

codegen/pkg/generator/events.go

@@ -19,11 +19,12 @@ import (
 var eventTemplates embed.FS
 
 type eventDefinition struct {
-	Name       string
-	Type       string
-	ObjectType string
-	SchemaName string
-	Method     string
+	Description []string
+	Name        string
+	Type        string
+	ObjectType  string
+	SchemaName  string
+	Method      string
 }
 
 func (g *Generator) collectEvents() ([]eventDefinition, error) {
@@ -49,12 +50,17 @@ func (g *Generator) collectEvents() ([]eventDefinition, error) {
 		if schema == nil || !schemaShouldGenerateClass(schema) {
 			return nil, fmt.Errorf("webhook %q has missing or unsupported object schema %q", eventType, schemaName)
 		}
+		var description []string
+		if text := strings.TrimSpace(item.Post.Description); text != "" {
+			description = strings.Split(strings.ReplaceAll(text, "*/", "* /"), "\n")
+		}
 		events = append(events, eventDefinition{
-			Name:       name + "Event",
-			Type:       eventType,
-			ObjectType: strcase.ToCamel(strings.NewReplacer(".", "_", "-", "_").Replace(schemaName)),
-			SchemaName: schemaName,
-			Method:     "on" + name,
+			Name:        name + "Event",
+			Description: description,
+			Type:        eventType,
+			ObjectType:  strcase.ToCamel(strings.NewReplacer(".", "_", "-", "_").Replace(schemaName)),
+			SchemaName:  schemaName,
+			Method:      "on" + name,
 		})
 	}
 	slices.SortFunc(events, func(a, b eventDefinition) int { return strings.Compare(a.Type, b.Type) })

codegen/pkg/generator/events_test.go

@@ -19,6 +19,7 @@ const webhookSpec = `{
   "webhooks": {
     "widgets.created": {"post": {
       "operationId": "WidgetCreatedWebhook",
+      "description": "Sent when a widget is created.\nFetch the widget to read its current state.",
       "x-object": {"$ref": "#/components/schemas/Widget"},
       "responses": {"2XX": {"description": "Accepted"}}
     }}
@@ -44,7 +45,7 @@ func TestGenerateEvents(t *testing.T) {
 		t.Fatal(err)
 	}
 	for file, snippets := range map[string][]string{
-		"Events/WidgetCreatedEvent.php": {"const TYPE = 'widgets.created'", "fetchObject(?RequestOptions $options = null): ?Widget", "Widget::class"},
+		"Events/WidgetCreatedEvent.php": {" * Sent when a widget is created.\n * Fetch the widget to read its current state.", "const TYPE = 'widgets.created'", "fetchObject(?RequestOptions $options = null): ?Widget", "Widget::class"},
 		"Events/EventFactory.php":       {"WidgetCreatedEvent::TYPE => new WidgetCreatedEvent", "new UnknownEvent"},
 		"Events/EventsHandler.php":      {"callable(WidgetCreatedEvent): void", "function onWidgetCreated(callable $callback): self"},
 		"Types/Widget.php":              {"class Widget", "public ?string $id"},

codegen/pkg/generator/templates/events/event.tmpl

@@ -9,7 +9,15 @@ use SumUp\Exception\EventObjectException;
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\{{.ObjectType}};
 
-/** A {{.Type}} notification. Fetch its object to retrieve the latest {{.ObjectType}}. */
+/**
+{{- if .Description}}
+{{- range .Description}}
+ *{{if .}} {{.}}{{end}}
+{{- end}}
+ *
+{{- end}}
+ * A {{.Type}} notification. Fetch its object to retrieve the latest {{.ObjectType}}.
+ */
 final class {{.Name}} extends EventNotification
 {
     public const TYPE = '{{.Type}}';

src/Events/CheckoutCreatedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Checkout;
 
-/** A checkouts.created notification. Fetch its object to retrieve the latest Checkout. */
+/**
+ * Sent once when a checkout is first observed in the checkout snapshot stream, even if it is already paid, failed, or expired. The event timestamp is the original checkout creation time.
+ *
+ * A checkouts.created notification. Fetch its object to retrieve the latest Checkout.
+ */
 final class CheckoutCreatedEvent extends EventNotification
 {
     public const TYPE = 'checkouts.created';

src/Events/CheckoutExpiredEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Checkout;
 
-/** A checkouts.expired notification. Fetch its object to retrieve the latest Checkout. */
+/**
+ * Sent once when a checkout is first observed with status EXPIRED. Expiry or deactivation without an upstream snapshot cannot produce this event. Later EXPIRED snapshots do not emit another expired event.
+ *
+ * A checkouts.expired notification. Fetch its object to retrieve the latest Checkout.
+ */
 final class CheckoutExpiredEvent extends EventNotification
 {
     public const TYPE = 'checkouts.expired';

src/Events/CheckoutFailedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Checkout;
 
-/** A checkouts.failed notification. Fetch its object to retrieve the latest Checkout. */
+/**
+ * Sent once when a checkout is first observed with status FAILED. A failed checkout can subsequently be retried and paid. Later FAILED snapshots do not emit another failed event.
+ *
+ * A checkouts.failed notification. Fetch its object to retrieve the latest Checkout.
+ */
 final class CheckoutFailedEvent extends EventNotification
 {
     public const TYPE = 'checkouts.failed';

src/Events/CheckoutPaidEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Checkout;
 
-/** A checkouts.paid notification. Fetch its object to retrieve the latest Checkout. */
+/**
+ * Sent once when a checkout is first observed with status PAID. Later PAID snapshots do not emit another paid event. The timestamp is the snapshot update time, not necessarily the payment completion time.
+ *
+ * A checkouts.paid notification. Fetch its object to retrieve the latest Checkout.
+ */
 final class CheckoutPaidEvent extends EventNotification
 {
     public const TYPE = 'checkouts.paid';

src/Events/CheckoutUpdatedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Checkout;
 
-/** A checkouts.updated notification. Fetch its object to retrieve the latest Checkout. */
+/**
+ * Sent when a checkout snapshot is published, including creation and payment status updates. Fetch the checkout to inspect its current status. This is not a guarantee that every checkout mutation produces a notification.
+ *
+ * A checkouts.updated notification. Fetch its object to retrieve the latest Checkout.
+ */
 final class CheckoutUpdatedEvent extends EventNotification
 {
     public const TYPE = 'checkouts.updated';

src/Events/MemberCreatedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Member;
 
-/** A members.created notification. Fetch its object to retrieve the latest Member. */
+/**
+ * Sent when a member is created, invited, or accepts an invitation for a merchant account.
+ *
+ * A members.created notification. Fetch its object to retrieve the latest Member.
+ */
 final class MemberCreatedEvent extends EventNotification
 {
     public const TYPE = 'members.created';

src/Events/MemberDeletedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Member;
 
-/** A members.deleted notification. Fetch its object to retrieve the latest Member. */
+/**
+ * Sent when a member is deleted from a merchant account.
+ *
+ * A members.deleted notification. Fetch its object to retrieve the latest Member.
+ */
 final class MemberDeletedEvent extends EventNotification
 {
     public const TYPE = 'members.deleted';

src/Events/MemberUpdatedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Member;
 
-/** A members.updated notification. Fetch its object to retrieve the latest Member. */
+/**
+ * Sent when a member is updated, disabled, rejected, or expires for a merchant account.
+ *
+ * A members.updated notification. Fetch its object to retrieve the latest Member.
+ */
 final class MemberUpdatedEvent extends EventNotification
 {
     public const TYPE = 'members.updated';

src/Events/ReaderCreatedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Reader;
 
-/** A readers.created notification. Fetch its object to retrieve the latest Reader. */
+/**
+ * Sent when a reader is paired to a merchant account and becomes available through the Readers API.
+ *
+ * A readers.created notification. Fetch its object to retrieve the latest Reader.
+ */
 final class ReaderCreatedEvent extends EventNotification
 {
     public const TYPE = 'readers.created';

src/Events/ReaderDeletedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Reader;
 
-/** A readers.deleted notification. Fetch its object to retrieve the latest Reader. */
+/**
+ * Sent when a reader is unpaired from a merchant account and is no longer available through the Readers API.
+ *
+ * A readers.deleted notification. Fetch its object to retrieve the latest Reader.
+ */
 final class ReaderDeletedEvent extends EventNotification
 {
     public const TYPE = 'readers.deleted';

src/Events/RoleCreatedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Role;
 
-/** A roles.created notification. Fetch its object to retrieve the latest Role. */
+/**
+ * Sent when a role is created for a merchant account.
+ *
+ * A roles.created notification. Fetch its object to retrieve the latest Role.
+ */
 final class RoleCreatedEvent extends EventNotification
 {
     public const TYPE = 'roles.created';

src/Events/RoleDeletedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Role;
 
-/** A roles.deleted notification. Fetch its object to retrieve the latest Role. */
+/**
+ * Sent when a role is deleted for a merchant account.
+ *
+ * A roles.deleted notification. Fetch its object to retrieve the latest Role.
+ */
 final class RoleDeletedEvent extends EventNotification
 {
     public const TYPE = 'roles.deleted';

src/Events/RoleUpdatedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Role;
 
-/** A roles.updated notification. Fetch its object to retrieve the latest Role. */
+/**
+ * Sent when a role is updated for a merchant account.
+ *
+ * A roles.updated notification. Fetch its object to retrieve the latest Role.
+ */
 final class RoleUpdatedEvent extends EventNotification
 {
     public const TYPE = 'roles.updated';

src/Events/SaleCompletedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Sale;
 
-/** A sales.completed notification. Fetch its object to retrieve the latest Sale. */
+/**
+ * Sent once per sale when its completion is observed: the sale is closed and has been fully paid. The event created_at is the sale's recorded completion time, rather than the time the notification is delivered. A delayed notification may arrive after subsequent updates, refunds, or chargebacks. Fetch the current sale using object.url with an access token that has the sales.read scope. The sale may briefly be unavailable while the Sales API catches up; retry fetching it after a 404 response. Automatic retries and manual redelivery may deliver the same event more than once; deduplicate by event id.
+ *
+ * A sales.completed notification. Fetch its object to retrieve the latest Sale.
+ */
 final class SaleCompletedEvent extends EventNotification
 {
     public const TYPE = 'sales.completed';

src/Events/SaleUpdatedEvent.php

@@ -9,7 +9,11 @@
 use SumUp\HttpClient\RequestOptions;
 use SumUp\Types\Sale;
 
-/** A sales.updated notification. Fetch its object to retrieve the latest Sale. */
+/**
+ * Sent when a closed, fully paid sale is published or updated, including subsequent refunds and chargebacks. The first notification can occur when the sale becomes fully paid and closed. Fetch the current sale using object.url with an access token that has the sales.read scope. The sale may briefly be unavailable while the Sales API catches up; retry fetching it after a 404 response. Notifications contain the sale identity rather than a snapshot, and delivery order is not guaranteed.
+ *
+ * A sales.updated notification. Fetch its object to retrieve the latest Sale.
+ */
 final class SaleUpdatedEvent extends EventNotification
 {
     public const TYPE = 'sales.updated';