feat: Add support for customer portal sessions (#103)

Author: davidgrayston-paddle

CHANGELOG.md

@@ -8,6 +8,11 @@ Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx
 
 ## [Unreleased]
 
+### Added
+
+- Support for customer portal sessions, see [related changelog](https://developer.paddle.com/changelog/2024/customer-portal-sessions?utm_source=dx&utm_medium=paddle-php-sdk)
+  - `Client->customerPortalSessions->create()`
+
 ### Fixed
 
 - `Client->notifications->replay()` now calls the correct endpoint

examples/customer_portal_session.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+use Paddle\SDK\Exceptions\ApiError;
+use Paddle\SDK\Exceptions\SdkExceptions\MalformedResponse;
+use Paddle\SDK\Resources\CustomerPortalSessions\Operations\CreateCustomerPortalSession;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$environment = Paddle\SDK\Environment::tryFrom(getenv('PADDLE_ENVIRONMENT') ?: '') ?? Paddle\SDK\Environment::SANDBOX;
+$apiKey = getenv('PADDLE_API_KEY') ?: null;
+$customerId = getenv('PADDLE_CUSTOMER_ID') ?: null;
+$subscriptionId = getenv('PADDLE_SUBSCRIPTION_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));
+
+// ┌───
+// │ Create Customer Portal Session │
+// └────────────────────────────────┘
+try {
+    $customerPortalSession = $paddle->customerPortalSessions->create(
+        $customerId,
+        new CreateCustomerPortalSession([$subscriptionId]),
+    );
+} catch (ApiError|MalformedResponse $e) {
+    var_dump($e);
+    exit;
+}
+
+echo sprintf("Created Customer Portal Session: %s\n", $customerPortalSession->id);
+echo sprintf("  - Customer ID: %s\n", $customerPortalSession->customerId);
+echo sprintf("  - Created At: %s\n", $customerPortalSession->createdAt->format(DATE_RFC3339_EXTENDED));
+echo sprintf("  - General Overview URL: %s\n", $customerPortalSession->urls->general->overview);
+
+foreach ($customerPortalSession->urls->subscriptions as $subscriptionUrl) {
+    echo sprintf("  - Subscription URLs: %s\n", $subscriptionUrl->id);
+    echo sprintf("      - Update Subscription Payment Method URL: %s\n", $subscriptionUrl->updateSubscriptionPaymentMethod);
+    echo sprintf("      - Cancel URL: %s\n", $subscriptionUrl->cancelSubscription);
+}

src/Client.php

@@ -22,6 +22,7 @@
 use Paddle\SDK\Resources\Addresses\AddressesClient;
 use Paddle\SDK\Resources\Adjustments\AdjustmentsClient;
 use Paddle\SDK\Resources\Businesses\BusinessesClient;
+use Paddle\SDK\Resources\CustomerPortalSessions\CustomerPortalSessionsClient;
 use Paddle\SDK\Resources\Customers\CustomersClient;
 use Paddle\SDK\Resources\Discounts\DiscountsClient;
 use Paddle\SDK\Resources\Events\EventsClient;
@@ -69,6 +70,7 @@ class Client
     public readonly TransactionsClient $transactions;
     public readonly AdjustmentsClient $adjustments;
     public readonly CustomersClient $customers;
+    public readonly CustomerPortalSessionsClient $customerPortalSessions;
     public readonly AddressesClient $addresses;
     public readonly BusinessesClient $businesses;
     public readonly DiscountsClient $discounts;
@@ -118,6 +120,7 @@ public function __construct(
         $this->adjustments = new AdjustmentsClient($this);
         $this->customers = new CustomersClient($this);
         $this->addresses = new AddressesClient($this);
+        $this->customerPortalSessions = new CustomerPortalSessionsClient($this);
         $this->businesses = new BusinessesClient($this);
         $this->discounts = new DiscountsClient($this);
         $this->subscriptions = new SubscriptionsClient($this);

src/Entities/CustomerPortalSession.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * |------
+ * | ! Generated code !
+ * | Altering this code will result in changes being overwritten |
+ * |-------------------------------------------------------------|.
+ */
+
+namespace Paddle\SDK\Entities;
+
+use Paddle\SDK\Entities\CustomerPortalSession\CustomerPortalSessionUrls;
+use Paddle\SDK\Notifications\Entities\Entity;
+
+class CustomerPortalSession implements Entity
+{
+    private function __construct(
+        public string $id,
+        public string $customerId,
+        public CustomerPortalSessionUrls $urls,
+        public \DateTimeInterface $createdAt,
+    ) {
+    }
+
+    public static function from(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            customerId: $data['customer_id'],
+            urls: CustomerPortalSessionUrls::from($data['urls']),
+            createdAt: DateTime::from($data['created_at']),
+        );
+    }
+}

src/Entities/CustomerPortalSession/CustomerPortalSessionGeneralUrl.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * |------
+ * | ! Generated code !
+ * | Altering this code will result in changes being overwritten |
+ * |-------------------------------------------------------------|.
+ */
+
+namespace Paddle\SDK\Entities\CustomerPortalSession;
+
+use Paddle\SDK\Notifications\Entities\Entity;
+
+class CustomerPortalSessionGeneralUrl implements Entity
+{
+    private function __construct(
+        public string $overview,
+    ) {
+    }
+
+    public static function from(array $data): self
+    {
+        return new self(
+            overview: $data['overview'],
+        );
+    }
+}

src/Entities/CustomerPortalSession/CustomerPortalSessionSubscriptionUrl.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * |------
+ * | ! Generated code !
+ * | Altering this code will result in changes being overwritten |
+ * |-------------------------------------------------------------|.
+ */
+
+namespace Paddle\SDK\Entities\CustomerPortalSession;
+
+use Paddle\SDK\Notifications\Entities\Entity;
+
+class CustomerPortalSessionSubscriptionUrl implements Entity
+{
+    private function __construct(
+        public string $id,
+        public string $cancelSubscription,
+        public string $updateSubscriptionPaymentMethod,
+    ) {
+    }
+
+    public static function from(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            cancelSubscription: $data['cancel_subscription'],
+            updateSubscriptionPaymentMethod: $data['update_subscription_payment_method'],
+        );
+    }
+}

src/Entities/CustomerPortalSession/CustomerPortalSessionUrls.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * |------
+ * | ! Generated code !
+ * | Altering this code will result in changes being overwritten |
+ * |-------------------------------------------------------------|.
+ */
+
+namespace Paddle\SDK\Entities\CustomerPortalSession;
+
+use Paddle\SDK\Notifications\Entities\Entity;
+
+class CustomerPortalSessionUrls implements Entity
+{
+    /**
+     * @param CustomerPortalSessionSubscriptionUrl[] $subscriptions
+     */
+    private function __construct(
+        public CustomerPortalSessionGeneralUrl $general,
+        public array $subscriptions,
+    ) {
+    }
+
+    public static function from(array $data): self
+    {
+        return new self(
+            general: CustomerPortalSessionGeneralUrl::from($data['general']),
+            subscriptions: array_map(
+                fn (array $item): CustomerPortalSessionSubscriptionUrl => CustomerPortalSessionSubscriptionUrl::from($item),
+                $data['subscriptions'] ?? [],
+            ),
+        );
+    }
+}

src/Resources/CustomerPortalSessions/CustomerPortalSessionsClient.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * |------
+ * | ! Generated code !
+ * | Altering this code will result in changes being overwritten |
+ * |-------------------------------------------------------------|.
+ */
+
+namespace Paddle\SDK\Resources\CustomerPortalSessions;
+
+use Paddle\SDK\Client;
+use Paddle\SDK\Entities\CustomerPortalSession;
+use Paddle\SDK\Exceptions\ApiError;
+use Paddle\SDK\Exceptions\SdkExceptions\MalformedResponse;
+use Paddle\SDK\Resources\CustomerPortalSessions\Operations\CreateCustomerPortalSession;
+use Paddle\SDK\ResponseParser;
+
+class CustomerPortalSessionsClient
+{
+    public function __construct(
+        private readonly Client $client,
+    ) {
+    }
+
+    /**
+     * @throws ApiError          On a generic API error
+     * @throws MalformedResponse If the API response was not parsable
+     */
+    public function create(string $customerId, CreateCustomerPortalSession $createOperation): CustomerPortalSession
+    {
+        $parser = new ResponseParser(
+            $this->client->postRaw("/customers/{$customerId}/portal-sessions", $createOperation),
+        );
+
+        return CustomerPortalSession::from($parser->getData());
+    }
+}

src/Resources/CustomerPortalSessions/Operations/CreateCustomerPortalSession.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Paddle\SDK\Resources\CustomerPortalSessions\Operations;
+
+use Paddle\SDK\FiltersUndefined;
+use Paddle\SDK\Undefined;
+
+class CreateCustomerPortalSession implements \JsonSerializable
+{
+    use FiltersUndefined;
+
+    /**
+     * @param string[] $subscriptionIds
+     */
+    public function __construct(
+        public readonly array|Undefined $subscriptionIds = new Undefined(),
+    ) {
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->filterUndefined([
+            'subscription_ids' => $this->subscriptionIds,
+        ]);
+    }
+}