feat: Support transaction revisions (#112)

Author: davidgrayston-paddle

CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx&utm_medium=paddle-php-sdk) for information about changes to the Paddle Billing platform, the Paddle API, and other developer tools.
 
+## [Unreleased]
+
+### Added
+
+- Added `transactions.revise` operation to revise a transaction and added `revised_at` to `Transaction` entity, see [related changelog](https://developer.paddle.com/changelog/2024/revise-transaction-customer-information?utm_source=dx&utm_medium=paddle-php-sdk).
+- Added support for `transaction.revised` notification, see [related changelog](https://developer.paddle.com/changelog/2024/revise-transaction-customer-information?utm_source=dx&utm_medium=paddle-php-sdk).
+
+### Fixed
+- Handle known entity types for events that are not supported by the current SDK version. `UndefinedEvent` will always return an `UndefinedEntity`.
+
 ## [1.8.0] - 2024-12-19
 
 ### Added

examples/transaction_revision.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+use Paddle\SDK\Exceptions\ApiError;
+use Paddle\SDK\Exceptions\SdkExceptions\MalformedResponse;
+use Paddle\SDK\Resources\Transactions\Operations\Revise\TransactionReviseAddress;
+use Paddle\SDK\Resources\Transactions\Operations\Revise\TransactionReviseBusiness;
+use Paddle\SDK\Resources\Transactions\Operations\Revise\TransactionReviseCustomer;
+use Paddle\SDK\Resources\Transactions\Operations\ReviseTransaction;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$environment = Paddle\SDK\Environment::tryFrom(getenv('PADDLE_ENVIRONMENT') ?: '') ?? Paddle\SDK\Environment::SANDBOX;
+$apiKey = getenv('PADDLE_API_KEY') ?: null;
+$transactionId = getenv('PADDLE_TRANSACTION_ID') ?: null;
+
+if (is_null($apiKey)) {
+    echo "You must provide the PADDLE_API_KEY in the environment:\n";
+    echo "PADDLE_API_KEY=your-key php examples/basic_usage.php\n";
+    exit(1);
+}
+
+$paddle = new Paddle\SDK\Client($apiKey, options: new Paddle\SDK\Options($environment));
+
+// ┌───
+// │ Revise Transaction │
+// └────────────────────┘
+try {
+    $transaction = $paddle->transactions->revise(
+        $transactionId,
+        new ReviseTransaction(
+            address: new TransactionReviseAddress(
+                firstLine: '123 Some Street',
+                secondLine: null,
+            ),
+            business: new TransactionReviseBusiness(
+                name: 'Some Business',
+                taxIdentifier: '555952383',
+            ),
+            customer: new TransactionReviseCustomer(
+                name: 'Some Name',
+            ),
+        ),
+    );
+} catch (ApiError|MalformedResponse $e) {
+    var_dump($e);
+    exit;
+}
+
+echo sprintf("Transaction ID: %s\n", $transaction->id);
+echo sprintf(" - Revised At: %s\n", $transaction->revisedAt->format(DATE_RFC3339_EXTENDED));

src/Entities/Event.php

@@ -7,6 +7,7 @@
 use Paddle\SDK\Entities\Event\EventTypeName;
 use Paddle\SDK\Notifications\Entities\Entity as NotificationEntity;
 use Paddle\SDK\Notifications\Entities\EntityFactory;
+use Paddle\SDK\Notifications\Entities\UndefinedEntity;
 use Paddle\SDK\Notifications\Events\UndefinedEvent;
 use Psr\Http\Message\ServerRequestInterface;
 
@@ -33,11 +34,16 @@ public static function from(array $data): self
             $event = UndefinedEvent::class;
         }
 
+        // Create an undefined entity for undefined events.
+        $entity = $event === UndefinedEvent::class
+            ? UndefinedEntity::from($data['data'])
+            : EntityFactory::create($data['event_type'], $data['data']);
+
         return $event::fromEvent(
             $data['event_id'],
             EventTypeName::from($data['event_type']),
             DateTime::from($data['occurred_at']),
-            EntityFactory::create($data['event_type'], $data['data']),
+            $entity,
             $data['notification_id'] ?? null,
         );
     }

src/Entities/Event/EventTypeName.php

@@ -52,6 +52,7 @@
  * @method static EventTypeName TransactionPastDue()
  * @method static EventTypeName TransactionPaymentFailed()
  * @method static EventTypeName TransactionReady()
+ * @method static EventTypeName TransactionRevised()
  * @method static EventTypeName TransactionUpdated()
  * @method static EventTypeName ReportCreated()
  * @method static EventTypeName ReportUpdated()
@@ -103,6 +104,7 @@ final class EventTypeName extends PaddleEnum
     private const TransactionPastDue = 'transaction.past_due';
     private const TransactionPaymentFailed = 'transaction.payment_failed';
     private const TransactionReady = 'transaction.ready';
+    private const TransactionRevised = 'transaction.revised';
     private const TransactionUpdated = 'transaction.updated';
     private const ReportCreated = 'report.created';
     private const ReportUpdated = 'report.updated';

src/Entities/Transaction.php

@@ -63,6 +63,7 @@ private function __construct(
         public Customer|null $customer,
         public Discount|null $discount,
         public array $availablePaymentMethods,
+        public \DateTimeInterface|null $revisedAt,
     ) {
     }
 
@@ -98,6 +99,7 @@ public static function from(array $data): self
             customer: isset($data['customer']) ? Customer::from($data['customer']) : null,
             discount: isset($data['discount']) ? Discount::from($data['discount']) : null,
             availablePaymentMethods: array_map(fn (string $item): AvailablePaymentMethods => AvailablePaymentMethods::from($item), $data['available_payment_methods'] ?? []),
+            revisedAt: isset($data['revised_at']) ? DateTime::from($data['revised_at']) : null,
         );
     }
 }

src/Notifications/Entities/Transaction.php

@@ -52,6 +52,7 @@ private function __construct(
         public \DateTimeInterface $createdAt,
         public \DateTimeInterface $updatedAt,
         public \DateTimeInterface|null $billedAt,
+        public \DateTimeInterface|null $revisedAt,
     ) {
     }
 
@@ -80,6 +81,7 @@ public static function from(array $data): self
             createdAt: DateTime::from($data['created_at']),
             updatedAt: DateTime::from($data['updated_at']),
             billedAt: isset($data['billed_at']) ? DateTime::from($data['billed_at']) : null,
+            revisedAt: isset($data['revised_at']) ? DateTime::from($data['revised_at']) : null,
         );
     }
 }

src/Notifications/Events/TransactionRevised.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Notifications\Events;
+
+use Paddle\SDK\Entities\Event;
+use Paddle\SDK\Entities\Event\EventTypeName;
+use Paddle\SDK\Notifications\Entities\Entity;
+use Paddle\SDK\Notifications\Entities\Transaction;
+
+final class TransactionRevised extends Event
+{
+    private function __construct(
+        string $eventId,
+        EventTypeName $eventType,
+        \DateTimeInterface $occurredAt,
+        public readonly Transaction $transaction,
+        string|null $notificationId,
+    ) {
+        parent::__construct($eventId, $eventType, $occurredAt, $transaction, $notificationId);
+    }
+
+    /**
+     * @param Transaction $data
+     */
+    public static function fromEvent(
+        string $eventId,
+        EventTypeName $eventType,
+        \DateTimeInterface $occurredAt,
+        Entity $data,
+        string|null $notificationId = null,
+    ): static {
+        return new self($eventId, $eventType, $occurredAt, $data, $notificationId);
+    }
+}

src/Resources/Transactions/Operations/Revise/TransactionReviseAddress.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Resources\Transactions\Operations\Revise;
+
+use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Undefined;
+
+class TransactionReviseAddress implements \JsonSerializable
+{
+    use FiltersUndefined;
+
+    public function __construct(
+        public readonly string|Undefined $firstLine = new Undefined(),
+        public readonly string|Undefined|null $secondLine = new Undefined(),
+        public readonly string|Undefined $city = new Undefined(),
+        public readonly string|Undefined $region = new Undefined(),
+    ) {
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->filterUndefined([
+            'first_line' => $this->firstLine,
+            'second_line' => $this->secondLine,
+            'city' => $this->city,
+            'region' => $this->region,
+        ]);
+    }
+}

src/Resources/Transactions/Operations/Revise/TransactionReviseBusiness.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Resources\Transactions\Operations\Revise;
+
+use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Undefined;
+
+class TransactionReviseBusiness implements \JsonSerializable
+{
+    use FiltersUndefined;
+
+    public function __construct(
+        public readonly string|Undefined $name = new Undefined(),
+        public readonly string|Undefined $taxIdentifier = new Undefined(),
+    ) {
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->filterUndefined([
+            'name' => $this->name,
+            'tax_identifier' => $this->taxIdentifier,
+        ]);
+    }
+}

src/Resources/Transactions/Operations/Revise/TransactionReviseCustomer.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Resources\Transactions\Operations\Revise;
+
+use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Undefined;
+
+class TransactionReviseCustomer implements \JsonSerializable
+{
+    use FiltersUndefined;
+
+    public function __construct(
+        public readonly string|Undefined $name = new Undefined(),
+    ) {
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->filterUndefined([
+            'name' => $this->name,
+        ]);
+    }
+}