Create schema classes [5267]

modules/ppcp-agentic-commerce/docs/testing.md

@@ -0,0 +1,9 @@
+# Testing
+
+Unit tests for this module are located in the `tests/PHPUnit/AgenticCommerce` directory.
+
+To run them, use the command:
+
+```sh
+ddev exec phpunit --filter AgenticCommerce
+```

modules/ppcp-agentic-commerce/services.php

@@ -9,4 +9,11 @@
 
 namespace WooCommerce\PayPalCommerce\AgenticCommerce;
 
-return array();
+use WooCommerce\PayPalCommerce\Vendor\Psr\Container\ContainerInterface;
+use WooCommerce\PayPalCommerce\AgenticCommerce\Response\ResponseFactory;
+
+return array(
+	'agentic.response.factory' => static function ( ContainerInterface $container ): ResponseFactory {
+		return new ResponseFactory();
+	},
+);

modules/ppcp-agentic-commerce/src/Errors/AgenticError.php

@@ -0,0 +1,68 @@
+<?php
+/**
+ * Base class for all agentic commerce REST errors.
+ *
+ * @package WooCommerce\PayPalCommerce\AgenticCommerce\Errors
+ */
+
+declare( strict_types = 1 );
+
+namespace WooCommerce\PayPalCommerce\AgenticCommerce\Errors;
+
+use RuntimeException;
+
+abstract class AgenticError {
+	/**
+	 * The error name is defined by the PayPal API, usually in upper-case, e.g. "INVALID_REQUEST".
+	 * Child classes must define this constant.
+	 */
+	protected const ERROR_NAME = '';
+
+	/**
+	 * The HTTP status code for the error, usually 400 or 500.
+	 * Child classes must define this constant.
+	 */
+	protected const STATUS_CODE = 0;
+
+	private string $message;
+	private ?array $details;
+
+	/**
+	 * Defines the error contents.
+	 *
+	 * @param string     $message Descriptive text of the error.
+	 * @param array|null $details Optional. Additional details about the error.
+	 * @throws RuntimeException When the error specs are incomplete.
+	 */
+	public function __construct( string $message, ?array $details = null ) {
+		if ( empty( static::ERROR_NAME ) ) {
+			throw new RuntimeException( 'Child classes must override ERROR_NAME constant' );
+		}
+		if ( ! is_numeric( static::STATUS_CODE ) || static::STATUS_CODE < 400 ) {
+			throw new RuntimeException( 'Child classes must define a valid STATUS_CODE constant' );
+		}
+		if ( empty( $message ) ) {
+			throw new RuntimeException( 'Error message cannot be empty' );
+		}
+
+		$this->message = $message;
+		$this->details = $details;
+	}
+
+	public function get_status_code(): int {
+		return static::STATUS_CODE;
+	}
+
+	public function to_array(): array {
+		$data = array(
+			'name'    => static::ERROR_NAME,
+			'message' => $this->message,
+		);
+
+		if ( $this->details ) {
+			$data['details'] = $this->details;
+		}
+
+		return $data;
+	}
+}

modules/ppcp-agentic-commerce/src/Errors/CartNotFoundError.php

@@ -0,0 +1,31 @@
+<?php
+// phpcs:disable Squiz.PHP.CommentedOutCode.Found
+
+declare( strict_types = 1 );
+
+namespace WooCommerce\PayPalCommerce\AgenticCommerce\Errors;
+
+/**
+ * When to use:
+ * - Invalid cart ID provided
+ */
+class CartNotFoundError extends AgenticError {
+	protected const ERROR_NAME  = 'CART_NOT_FOUND';
+	protected const STATUS_CODE = 404;
+}
+
+/*
+Sample:
+{
+	"name": "CART_NOT_FOUND",
+	"message": "Cart with ID 'CART-MISSING-123' does not exist",
+	"debug_id": "ERROR-404-12345",
+	"details": [
+		{
+			"field": "cartId",
+			"issue": "NOT_FOUND",
+			"description": "Cart with ID 'CART-MISSING-123' does not exist for merchant 'MERCHANT_789'. Verify cart ID or create a new cart."
+		}
+	]
+}
+*/

modules/ppcp-agentic-commerce/src/Errors/InvalidRequestError.php

@@ -0,0 +1,32 @@
+<?php
+// phpcs:disable Squiz.PHP.CommentedOutCode.Found
+
+declare( strict_types = 1 );
+
+namespace WooCommerce\PayPalCommerce\AgenticCommerce\Errors;
+
+/**
+ * When to use:
+ * - Empty request body
+ * - Malformed request
+ * - Missing mandatory fields
+ */
+class InvalidRequestError extends AgenticError {
+	protected const ERROR_NAME  = 'INVALID_REQUEST';
+	protected const STATUS_CODE = 400;
+}
+
+/*
+Sample:
+{
+	"name": "INVALID_REQUEST",
+	"message": "Required field 'items' is missing",
+	"details": [
+		{
+			"field": "items",
+			"issue": "MISSING_REQUIRED_FIELD",
+			"description": "The items field is required and cannot be empty."
+		}
+	]
+}
+*/

modules/ppcp-agentic-commerce/src/Response/CartResponse.php

@@ -0,0 +1,63 @@
+<?php
+/**
+ * PayPal Cart Response.
+ *
+ * @package WooCommerce\PayPalCommerce\AgenticCommerce\Response
+ */
+
+declare( strict_types = 1 );
+
+namespace WooCommerce\PayPalCommerce\AgenticCommerce\Response;
+
+use WooCommerce\PayPalCommerce\AgenticCommerce\Schema\PayPalCart;
+
+class CartResponse {
+	protected ?PayPalCart $cart = null;
+
+	/**
+	 * The cart ID used by the API to reference to an existing cart.
+	 *
+	 * @var string The cart ID is usually part of the REST endpoint path.
+	 */
+	protected string $cart_id = '';
+
+	/**
+	 * Used to track cart lifecycle.
+	 * Possible values: CREATED, INCOMPLETE, READY, COMPLETED
+	 *
+	 * @var string Business workflow state.
+	 */
+	protected string $status = 'INCOMPLETE';
+
+	/**
+	 * Used to determine the next step.
+	 * Possible values: VALID, INVALID, REQUIRES_ADDITIONAL_INFORMATION
+	 *
+	 * @var string Data validation state.
+	 */
+	protected string $validation_status = 'INVALID';
+
+	/**
+	 * The payment method token, used to verify checkout.
+	 */
+	protected string $token = '';
+
+	public function __construct( PayPalCart $cart ) {
+		$this->cart = $cart;
+		// todo - set the other props of this class, once the flow becomes more clear.
+	}
+
+	public function to_array(): array {
+		// Always set via the constructor, but the IDE does not believe it.
+		assert( $this->cart instanceof PayPalCart );
+
+		$data = array(
+			'id'                => $this->cart_id,
+			'status'            => $this->status,
+			'validation_status' => $this->validation_status,
+			'validation_issues' => $this->cart->validate(),
+		);
+
+		return array_merge( $data, $this->cart->to_array() );
+	}
+}

modules/ppcp-agentic-commerce/src/Response/NewCartResponse.php

@@ -0,0 +1,31 @@
+<?php
+/**
+ * PayPal Cart Response (new cart created).
+ *
+ * @package WooCommerce\PayPalCommerce\AgenticCommerce\Response\
+ */
+
+declare( strict_types = 1 );
+
+namespace WooCommerce\PayPalCommerce\AgenticCommerce\Response;
+
+use WooCommerce\PayPalCommerce\AgenticCommerce\Schema\PayPalCart;
+
+class NewCartResponse extends CartResponse {
+	public function __construct( PayPalCart $cart, string $token ) {
+		parent::__construct( $cart );
+		$this->token = $token;
+	}
+
+	public function to_array(): array {
+		$data = parent::to_array();
+
+		$data['payment_method'] = array(
+			'type'         => 'paypal',
+			'token'        => $this->token,
+			'approval_url' => 'not-implemented',
+		);
+
+		return $data;
+	}
+}

modules/ppcp-agentic-commerce/src/Response/PaidCartResponse.php

@@ -0,0 +1,38 @@
+<?php
+/**
+ * PayPal Cart Response (cart checkout confirmed).
+ *
+ * @package WooCommerce\PayPalCommerce\AgenticCommerce\Response
+ */
+
+declare( strict_types = 1 );
+
+namespace WooCommerce\PayPalCommerce\AgenticCommerce\Response;
+
+use WC_Order;
+use WooCommerce\PayPalCommerce\AgenticCommerce\Schema\PayPalCart;
+
+class PaidCartResponse extends CartResponse {
+	/**
+	 * @var WC_Order|null The WooCommerce order which was created during checkout.
+	 */
+	protected ?WC_Order $wc_order = null;
+
+	public function __construct( PayPalCart $cart, WC_Order $wc_order ) {
+		parent::__construct( $cart );
+		$this->wc_order = $wc_order;
+	}
+
+	public function to_array(): array {
+		$data = parent::to_array();
+
+		if ( $this->wc_order ) {
+			$data['payment_confirmation'] = array(
+				'merchant_order_number' => $this->wc_order->get_id(),
+				'order_review_page'     => $this->wc_order->get_checkout_order_received_url(),
+			);
+		}
+
+		return $data;
+	}
+}

modules/ppcp-agentic-commerce/src/Response/ResponseFactory.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * Factory service for the REST response objects.
+ *
+ * @package WooCommerce\PayPalCommerce\AgenticCommerce\Response
+ */
+
+declare( strict_types = 1 );
+
+namespace WooCommerce\PayPalCommerce\AgenticCommerce\Response;
+
+use WC_Order;
+use WooCommerce\PayPalCommerce\AgenticCommerce\Schema\PayPalCart;
+
+class ResponseFactory {
+	public function new_cart( PayPalCart $cart ): NewCartResponse {
+		return new NewCartResponse( $cart, 'not-implemented' );
+	}
+
+	public function from_order( WC_Order $order, PayPalCart $cart ): PaidCartResponse {
+		return new PaidCartResponse( $cart, $order );
+	}
+
+	public function from_cart( PayPalCart $cart ): CartResponse {
+		return new CartResponse( $cart );
+	}
+}