fix(ucp): always emit absolute order.permalink_url so completed checkouts pass SDK response validation

[Björn Meyer (BrocksiNet)]

This is Robin Schulte (@relativvv)'s fix from #151, rebased onto current main so the diff is the fix. He is the commit author; #151 is closed in favour of this. Nothing of the fix changed — see What I changed below for the two editorial decisions I had to make, both of which want his call.

#151 showed 2,079 additions / 261 deletions across 49 files. This shows 131 / 7 across 9. The difference was branch history: its branch carried commits from #147, #148, #149, #156, #154, #155 and #157 plus a merge of main — an admin-UI rewrite, an OpenAI export template, docs — all of which are already on main.

---

The bug

types/order_confirmation.json requires both id and permalink_url. The SDK model drops a null one:

return array_filter(['id' => $this->id, 'permalink_url' => $this->permalinkUrl], fn($v) => $v !== null);

ShopwareDataMapper passed the nullable continue URL as the permalink, so on a sales channel without a continueUrlTemplate the field was omitted, branch 0 (Checkout) of the response's root oneOf failed, and the SDK rejected the shop's own response:

FAIL shopware-ucp-checkout-complete: validation: Validation failed for schema
     "checkout.complete.response". ($ must match exactly one allowed schema.)

The order is placed. Only the response fails — so the agent is told its purchase failed and never learns the order id, after which order.get has no id to read. Severity is higher than the message suggests.

The fix

OrderPermalinkBuilder produces an absolute {baseUri}/ucp/v1/orders/{id}, threaded through CheckoutCompleter and ShopwareCheckoutAdapter into ShopwareDataMapper::toCompletedCheckout(). A permalink is not a continue URL and should not depend on optional configuration.

Verified on a trunk lane, with no continueUrlTemplate configured

The lane had to be made honest first — clearing the template moved the MCP evals store suite from 34 passed / 1 failed to 30 passed, 3 failed, 2 skipped, byte-identical to CI. That single config value was the whole reason this never reproduced locally.

With this branch, same configuration:

checkout.complete   order.permalink_url = http://trunk.localhost:8088/ucp/v1/orders/{orderId}
order.get           permalink_url       = http://trunk.localhost:8088/account/order/{orderId}

Store suite: 34 passed, 1 failed, 0 skipped
  PASS order-get (guest)      ← the typed refusal from #162, asserted as the correct answer
  PASS order-get (customer)   ← a real read-back, passing for the first time
  FAIL a signed-in buyer can place a second order   ← #163, unrelated, expected

Plugin gates on the lane: 565 unit tests green, cs clean, phpstan 93 findings — identical to the baseline count, nothing new.

---

What I changed, and why each wants Robin Schulte (@relativvv)'s call

1. Dropped the CheckoutStatus $status parameter. The original commit says "Stacked on #130 (shares the toCompletedCheckout signature)", and its signature was:

toCompletedCheckout(…, ?string $continueUrl = null, CheckoutStatus $status = CheckoutStatus::Completed, ?string $orderPermalinkUrl = null)

$status is #130's, not the permalink's, and #130 is not on main. Here it is:

toCompletedCheckout(…, ?string $continueUrl = null, ?string $orderPermalinkUrl = null)

Question: should #130 own that signature change and add $status on top of this, or would you rather this PR carried it? I took the narrower reading so the permalink fix can merge without waiting on the payment-state discussion, but it is your call which PR owns the signature.

2. Dropped #130's two payment-status tests — testUnpaidPlacedOrderIsReportedCompleteInProgress and testPaidPlacedOrderIsReportedCompleted. They assert #130's behaviour, not the permalink's, and they cannot compile without $status. They should travel with #130.

All four of the original permalink test additions are intact (OrderPermalinkBuilderTest plus the mapper, completer and adapter cases). Two of them I had to re-seat by hand: the conflict boundary had spliced them into the middle of a helper method, so if the placement looks different from what you wrote, that is why.

One thing I did not verify

order.get returns permalink_url = {baseUri}/account/order/{orderId}. Shopware's guest order page resolves a deep-link code, not an order id, so that URL may not open for a guest — while the completion permalink points at the UCP endpoint and is unaffected. I have not tested it either way. Given the spec calls the permalink "the authoritative reference for the full order experience", it seems worth a look: should the order-view permalink use deepLinkCode for guests, or point at the UCP endpoint like the completion one does?

Context

• Found by the MCP evals store journey; it is what blocks that journey in CI.
• fix(ucp): refuse a guest order read in UCP's vocabulary, not Shopware's #162 (merged) is why the guest order-get line above is a PASS rather than a mystery — it makes the refusal typed.
• UCP: a cart can place only one order — the checkout id is a context token Shopware retires at completion #163 / UCP: an authenticated Shopware session reaches order reads but not the cart or checkout #164 are the two open findings from the same exercise, both needing a design decision rather than a patch.
• ucp-php-sdk#114 makes the SDK side of this legible: oneOf failures now name the branch and the field, and OrderConfirmation::$permalinkUrl becomes required so the invalid object cannot be built. That PR does not replace this one — the business still has to supply the URL.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2ae1a2ccd5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".