feat: adopt the pinned spec target and the shared base, and close the conformance gaps

.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  phpstan:
+    name: PHPStan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout module
+        uses: actions/checkout@v4
+
+      - name: Allow phpstan/extension-installer composer plugin
+        run: composer config --global allow-plugins.phpstan/extension-installer true
+
+      # A module repository has no Magento to analyse against, so one is built around it.
+      - name: Set up Magento project with module
+        id: magento
+        uses: magebitcom/setup-magento-module-action@v1
+        with:
+          magento-version: "2.4.7-p3"
+          php-version: "8.3"
+          composer-auth-user: ${{ secrets.MAGENTO_AUTH_USER }}
+          composer-auth-pass: ${{ secrets.MAGENTO_AUTH_PASS }}
+          extra-packages: >-
+            phpstan/phpstan:^2.0
+            bitexpert/phpstan-magento:^0.42
+            phpstan/extension-installer:^1.4
+            phpunit/phpunit:^9.5
+            opis/json-schema:^2.6
+
+      # bitexpert/phpstan-magento only invents a factory class when Composer cannot find a real
+      # one, and that fallback is broken on newer phpstan/phpstan. Compiling writes the real
+      # factories to disk, so the fallback never runs.
+      - name: Generate DI factories for PHPStan
+        working-directory: ${{ steps.magento.outputs.project-path }}
+        run: |
+          php bin/magento module:enable --all
+          php -d memory_limit=-1 bin/magento setup:di:compile
+
+      # The factories compiled above are loaded by a Magento autoloader at runtime, not through
+      # Composer, so PHPStan has to be pointed at them. Left unfound, it invents its own and trips
+      # over the broken fallback described above.
+      - name: Run PHPStan
+        working-directory: ${{ steps.magento.outputs.project-path }}
+        run: |
+          cat > phpstan-ci.neon <<'NEON'
+          includes:
+              - ${{ steps.magento.outputs.module-path }}/phpstan.neon
+          parameters:
+              scanDirectories:
+                  - generated/code
+          NEON
+          vendor/bin/phpstan analyse "${{ steps.magento.outputs.module-path }}" \
+            -c phpstan-ci.neon --no-progress --memory-limit=4G
+
+  unit-tests:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout module
+        uses: actions/checkout@v4
+
+      - name: Set up Magento project with module
+        id: magento
+        uses: magebitcom/setup-magento-module-action@v1
+        with:
+          magento-version: "2.4.7-p3"
+          php-version: "8.3"
+          composer-auth-user: ${{ secrets.MAGENTO_AUTH_USER }}
+          composer-auth-pass: ${{ secrets.MAGENTO_AUTH_PASS }}
+          extra-packages: >-
+            phpunit/phpunit:^9.5
+            opis/json-schema:^2.6
+
+      # Extension attribute interfaces such as CartExtensionInterface are generated, and tests that
+      # mock one need the real thing rather than the empty stub that ships in vendor.
+      - name: Generate the extension attribute classes
+        working-directory: ${{ steps.magento.outputs.project-path }}
+        run: |
+          php bin/magento module:enable --all
+          php -d memory_limit=-1 bin/magento setup:di:compile
+
+      - name: Run unit tests
+        working-directory: ${{ steps.magento.outputs.project-path }}
+        run: >-
+          vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist
+          "${{ steps.magento.outputs.module-path }}/Test/Unit" --testdox

Api/Data/CheckoutMetaInterface.php

@@ -22,6 +22,7 @@ interface CheckoutMetaInterface
     public const ORDER_ID = 'order_id';
     public const WEBHOOK_URL = 'webhook_url';
     public const SUBMITTED_FULFILLMENT = 'submitted_fulfillment';
+    public const BUYER_CONSENT = 'buyer_consent';
     public const CREATED_AT = 'created_at';
     public const UPDATED_AT = 'updated_at';
 
@@ -105,6 +106,19 @@ public function getSubmittedFulfillment(): ?string;
      */
     public function setSubmittedFulfillment(?string $submittedFulfillment): self;
 
+    /**
+     * The data-processing consent the agent recorded for this buyer, as JSON.
+     *
+     * @return string|null
+     */
+    public function getBuyerConsent(): ?string;
+
+    /**
+     * @param string|null $buyerConsent
+     * @return $this
+     */
+    public function setBuyerConsent(?string $buyerConsent): self;
+
     /**
      * Get created at
      *

Api/Data/OrderAdjustmentInterface.php

@@ -0,0 +1,76 @@
+<?php
+
+/**
+ * This file is part of the Magebit_UniversalCommerce package.
+ *
+ * @copyright Copyright (c) 2026 Magebit, Ltd. (https://magebit.com/)
+ * @author    Magebit <info@magebit.com>
+ * @license   MIT
+ */
+
+declare(strict_types=1);
+
+namespace Magebit\UniversalCommerce\Api\Data;
+
+/**
+ * One post-order adjustment an agent asked this store to record against an order.
+ */
+interface OrderAdjustmentInterface
+{
+    public const ENTITY_ID = 'entity_id';
+    public const ORDER_ID = 'order_id';
+    public const ADJUSTMENT_ID = 'adjustment_id';
+    public const PAYLOAD = 'payload';
+    public const CREATED_AT = 'created_at';
+    public const UPDATED_AT = 'updated_at';
+
+    /**
+     * @return int|null
+     */
+    public function getEntityId(): ?int;
+
+    /**
+     * @return int|null
+     */
+    public function getOrderId(): ?int;
+
+    /**
+     * @param int $orderId
+     * @return $this
+     */
+    public function setOrderId(int $orderId): self;
+
+    /**
+     * @return string|null
+     */
+    public function getAdjustmentId(): ?string;
+
+    /**
+     * @param string $adjustmentId
+     * @return $this
+     */
+    public function setAdjustmentId(string $adjustmentId): self;
+
+    /**
+     * The adjustment as the agent submitted it, as JSON.
+     *
+     * @return string|null
+     */
+    public function getPayload(): ?string;
+
+    /**
+     * @param string $payload
+     * @return $this
+     */
+    public function setPayload(string $payload): self;
+
+    /**
+     * @return string|null
+     */
+    public function getCreatedAt(): ?string;
+
+    /**
+     * @return string|null
+     */
+    public function getUpdatedAt(): ?string;
+}

Api/Data/TotalTypeInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * This file is part of the Magebit_UniversalCommerce package.
+ *
+ * @copyright Copyright (c) 2025 Magebit, Ltd. (https://magebit.com/)
+ * @author    Magebit <info@magebit.com>
+ * @license   MIT
+ */
+
+declare(strict_types=1);
+
+namespace Magebit\UniversalCommerce\Api\Data;
+
+/**
+ * The total types this module emits. UCP `2026-04-08` made `total.type` an open string — it documents
+ * these as well-known values in prose and lets businesses add their own — so the vocabulary is no
+ * longer generated from the schema and belongs to whoever writes the totals.
+ */
+interface TotalTypeInterface
+{
+    public const TYPE_SUBTOTAL = 'subtotal';
+    public const TYPE_ITEMS_DISCOUNT = 'items_discount';
+    public const TYPE_ITEMS_BASE_AMOUNT = 'items_base_amount';
+    public const TYPE_DISCOUNT = 'discount';
+    public const TYPE_FULFILLMENT = 'fulfillment';
+    public const TYPE_TAX = 'tax';
+    public const TYPE_FEE = 'fee';
+    public const TYPE_TOTAL = 'total';
+}