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

[Robin Schulte (relativvv)]

Problem

The UCP checkout/order response schema requires order.permalink_url to be a non-null absolute URI (format: uri). ShopwareDataMapper passed the nullable continue URL as the permalink, so on sales channels without a continueUrlTemplate, OrderConfirmation::toArray() array_filters the null away and the field is omitted. The SDK then validates the shop's own response (ShoppingOperationExecutor → DefaultProtocolValidator::validateResponse) against the checkout.*.response schema (a 2-branch oneOf), which fails — surfacing as the opaque $ must match exactly one allowed schema on GET and complete, for every client, once a checkout carries an order.

Reproduced with the SDK's own GeneratedSchemaValidator: an order without permalink_url → INVALID; with it → VALID.

Fix

• New OrderPermalinkBuilder → {baseUri}/ucp/v1/orders/{id} (mirrors the existing order-view permalink logic; points at the UCP order endpoint so it stays machine-resolvable on headless/agent sales channels with no human storefront order page).
• Thread an explicit orderPermalinkUrl through CheckoutCompleter and ShopwareCheckoutAdapter into ShopwareDataMapper::toCompletedCheckout; OrderConfirmation uses orderPermalinkUrl ?? continueUrl.
• Unit tests for the builder + mapper (permalink present / continue-url fallback).

Notes

• Stacked on fix: never report unpaid orders as completed; advertise delegated payment handlers #130 (shares the toCompletedCheckout signature). Rebase onto main once fix: never report unpaid orders as completed; advertise delegated payment handlers #130 merges.
• Verified live end-to-end: harness completeCheckout → x402 returned → USDC settled on Base mainnet → order paid.

Draft pending review.

[Björn Meyer (BrocksiNet)]

Resolved the conflict with main and pushed a merge commit — history untouched, nothing dropped.

What conflicted: tests/Unit/ShopwareDataMapperTest.php. Both sides had inserted new tests after the same #[Test] anchor, so git couldn't tell whether to interleave or stack them. Kept both — your two permalink tests and main's promotion/cart-message block. The only edit is a closing brace and a re-opened attribute so the two sets sit side by side.

After the merge: composer test 546 green (9 skipped), composer cs clean.

One local wrinkle, not yours: the test bootstrap's teardown reports Removal failed, shopware/agentic-commerce is still present on a lane whose root composer.json requires the plugin. The suite runs and passes; that line is the uninstall step, not a test failure.

This is the third instance of one defect class

Worth naming, because the pattern is more useful than the three fixes:

#	mapped response	why the schema rejected it
#155	promotion line with a negative unit price	emitted as a per-line subtotal, which types/total.json constrains to minimum: 0
#159	cart message	type: cart_error, and types/message.json pins type to a const of error/warning/info
this	completed checkout's order	permalink_url omitted when continueUrlTemplate is unset, and it is a required absolute URI

Every one surfaces as the same opaque $ must match exactly one allowed schema from the shop validating its own response, and every one was invisible until an agent hit the exact path.

The durable fix is a fixture, not a fourth patch. #159 added UcpResponseSchemaTest, which runs the real GeneratedSchemaValidator against real mapped responses across all seven cart and checkout operations — but its fixture is a cart. Your defect lives on the completed-checkout path, where an order exists, and that fixture never builds one. So #159's test would not have caught this, and the next mapping drift on that path will also go unnoticed.

Could you add a completed-checkout case to UcpResponseSchemaTest here — toCompletedCheckout() through assertValidates('checkout.complete.response', …) — rather than only the two unit assertions on toArray()? Your unit tests prove the permalink is populated; a schema case proves the whole response is conformant, which is the thing that actually broke. That closes the class instead of the instance. Happy to add it myself if you'd rather.

Base branch

You're stacked on #130, and #130's Part B (reporting a placed-but-unpaid order as complete_in_progress) looks superseded: the spec says completed means "Order placed successfully" and complete_in_progress means "Business is processing the Complete Checkout request", and Lukas Rump (@lukasrump)'s #152 already implements the spec-shaped alternative (requires_escalation + continue_url, order not placed). Details on #130.

If Part B comes out, this will want rebasing onto main — it only needs Part A's toCompletedCheckout signature, and I don't think it needs even that. Flagging so the base doesn't quietly carry a contested change into main with your fix.

[Björn Meyer (BrocksiNet)]

Closing in favour of #165, which is this same fix — your commit, you as author — rebased onto current main.

Nothing about the fix was in question. It was the diff: this PR reports 2,079 additions / 261 deletions across 49 files, because the branch carries #147, #148, #149, #156, #154, #155 and #157 plus a merge of main, all of which are already on main. Rebased, the same change is 131 / 7 across 9 files.

Two editorial calls I had to make, both flagged as questions for you in #165's description:

• the CheckoutStatus $status parameter is dropped. Your commit notes it is stacked on fix: never report unpaid orders as completed; advertise delegated payment handlers #130 and shares the toCompletedCheckout signature; fix: never report unpaid orders as completed; advertise delegated payment handlers #130 is not on main, so fix(ucp): always emit absolute order.permalink_url so completed checkouts pass SDK response validation #165 carries only ?string $orderPermalinkUrl. Whether fix: never report unpaid orders as completed; advertise delegated payment handlers #130 or the permalink PR should own that signature change is your call.
• fix: never report unpaid orders as completed; advertise delegated payment handlers #130's two payment-status tests are dropped for the same reason — they assert fix: never report unpaid orders as completed; advertise delegated payment handlers #130's behaviour and cannot compile without $status.

All four of your permalink test additions are intact; two I had to re-seat because the conflict boundary had spliced them into the middle of a helper method.

Also verified it, which this PR's own diff had made hard: with continueUrlTemplate cleared — the condition CI runs under, and the only reason this never reproduced on a dev lane — the fix takes the MCP evals store suite from 30 passed / 3 failed / 2 skipped to 34 / 1, and order.get passes for the first time. Numbers and the measured URLs are in #165.

One question in there worth your eye: order.get's permalink is {baseUri}/account/order/{orderId}, and Shopware's guest order page resolves a deep-link code rather than an order id — so that link may not open for a guest. Untested either way; the completion permalink points at the UCP endpoint and is unaffected.

Thanks — the diagnosis in your description is what made the CI failure legible, and it also produced ucp-php-sdk#114, which makes the SDK name the branch and the field instead of only saying $ must match exactly one allowed schema.