@danielseres9/adobe-commerce-checkout 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- Initial package structure for Adobe Commerce Checkout Drop-ins integration.
+- Added OOPE GraphQL fragments, checkout/order transformers, App Builder payment client, and checkout place-order helpers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Worldpay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# Worldpay Adobe Commerce Checkout
+
+Worldpay integration package for Adobe Commerce Checkout Drop-ins and OOPE payment methods.
+
+This package contains the storefront-side logic required to connect an Adobe Commerce Storefront checkout to a Worldpay App Builder payment endpoint. It is intended for AEM Edge Delivery Services storefronts that use Adobe Commerce Drop-ins.
+
+## What It Does
+
+- Adds Checkout Drop-in GraphQL fragments for OOPE payment configuration.
+- Preserves `oope_payment_method_config` in the checkout cart model.
+- Detects `Worldpay` and `WorldpayLocal*` payment methods.
+- Places the Adobe Commerce order before starting payment.
+- Calls the OOPE `backend_integration_url`, usually the Worldpay App Builder `create-payment` action.
+- Sends `orderEntityId`, `merchantConfigId`, `returnUrl`, and `paymentMethod`.
+- Redirects the shopper to the Worldpay middleware redirect/HPP page.
+- Displays pending Worldpay orders as `Pending Payment`.
+
+## Install
+
+```bash
+npm install @danielseres9/adobe-commerce-checkout
+```
+
+For local package development from a sibling checkout:
+
+```json
+{
+  "dependencies": {
+    "@danielseres9/adobe-commerce-checkout": "file:../worldpay-adobe-commerce-checkout"
+  }
+}
+```
+
+## Storefront Wiring
+
+### 1. Extend Checkout GraphQL
+
+In `build.mjs`:
+
+```js
+import { overrideGQLOperations } from '@dropins/build-tools/gql-extend.js';
+import { worldpayCheckoutGqlOperations } from '@danielseres9/adobe-commerce-checkout';
+
+overrideGQLOperations([
+  {
+    npm: '@dropins/storefront-checkout',
+    operations: worldpayCheckoutGqlOperations,
+  },
+]);
+```
+
+### 2. Preserve OOPE Config In Checkout Data
+
+In the checkout initializer:
+
+```js
+import { worldpayCheckoutModelTransformer } from '@danielseres9/adobe-commerce-checkout';
+
+initialize(checkoutApi, {
+  models: {
+    CartModel: {
+      transformer: worldpayCheckoutModelTransformer,
+    },
+  },
+});
+```
+
+### 3. Handle Worldpay Place Order
+
+Inside the checkout block's `handlePlaceOrder` callback:
+
+```js
+import * as orderApi from '@dropins/storefront-order/api.js';
+import { events } from '@dropins/tools/event-bus.js';
+import {
+  handleWorldpayPlaceOrder,
+  isWorldpayPaymentMethod,
+} from '@danielseres9/adobe-commerce-checkout';
+
+if (isWorldpayPaymentMethod(code)) {
+  await handleWorldpayPlaceOrder({
+    cartId,
+    code,
+    cartData: events.lastPayload('checkout/updated')
+      ?? events.lastPayload('checkout/initialized'),
+    buildOrderUrl: buildOrderDetailsUrl,
+    placeOrder: orderApi.placeOrder,
+  });
+  return;
+}
+```
+
+### 4. Transform Worldpay Pending Orders
+
+In the order initializer:
+
+```js
+import { worldpayOrderDataModelTransformer } from '@danielseres9/adobe-commerce-checkout';
+
+initialize(orderApi, {
+  models: {
+    OrderDataModel: {
+      transformer: worldpayOrderDataModelTransformer,
+    },
+  },
+});
+```
+
+## OOPE Requirements
+
+The Adobe Commerce OOPE method must expose `oope_payment_method_config.backend_integration_url`. That URL should point to the Worldpay App Builder `create-payment` action and include or otherwise allow resolving a `merchantConfigId`.
+
+Example:
+
+```text
+https://<namespace>.adobeioruntime.net/api/v1/web/adobe_worldpay_access/create-payment?merchantConfigId=<merchant-id>
+```
+
+## Runtime Payload
+
+The package posts this JSON body to App Builder:
+
+```json
+{
+  "orderEntityId": 123,
+  "merchantConfigId": "merchant-config-id",
+  "returnUrl": "https://merchant.example/order-details?orderRef=...",
+  "paymentMethod": "Worldpay"
+}
+```
+
+App Builder should return:
+
+```json
+{
+  "redirectUrl": "https://middleware.example/redirect-page/..."
+}
+```
+
+The browser is then redirected to `redirectUrl`.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@danielseres9/adobe-commerce-checkout",
+  "version": "0.1.0",
+  "description": "Worldpay integration package for Adobe Commerce Checkout Drop-ins",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./app-builder-client.js": "./src/app-builder-client.js",
+    "./checkout.js": "./src/checkout.js",
+    "./constants.js": "./src/constants.js",
+    "./gql.js": "./src/gql.js",
+    "./order.js": "./src/order.js",
+    "./transformers.js": "./src/transformers.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "worldpay",
+    "adobe-commerce",
+    "aem",
+    "edge-delivery-services",
+    "checkout",
+    "drop-ins",
+    "oope"
+  ],
+  "peerDependencies": {
+    "@dropins/storefront-checkout": ">=3.2.0 <4",
+    "@dropins/storefront-order": ">=3.3.0 <4",
+    "@dropins/tools": ">=1.8.0 <2"
+  },
+  "peerDependenciesMeta": {
+    "@dropins/storefront-checkout": {
+      "optional": true
+    },
+    "@dropins/storefront-order": {
+      "optional": true
+    },
+    "@dropins/tools": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/danielseres9/worldpay-adobe-commerce-checkout.git"
+  },
+  "bugs": {
+    "url": "https://github.com/danielseres9/worldpay-adobe-commerce-checkout/issues"
+  },
+  "homepage": "https://github.com/danielseres9/worldpay-adobe-commerce-checkout#readme"
+}

package/src/app-builder-client.js

@@ -0,0 +1,115 @@
+import { WORLDPAY_PAYMENT_METHOD } from './constants.js';
+
+export function getWorldpayMethodConfig(method) {
+  return method?.additionalData?.oope_payment_method_config
+    ?? method?.oope_payment_method_config;
+}
+
+export function getWorldpayBackendUrl(cartData, paymentMethodCode) {
+  const selectedMethod = cartData?.selectedPaymentMethod;
+  const availableMethod = cartData?.availablePaymentMethods?.find(
+    (method) => method.code === paymentMethodCode,
+  );
+  const config = getWorldpayMethodConfig(
+    selectedMethod?.code === paymentMethodCode
+      ? selectedMethod
+      : availableMethod,
+  );
+
+  return config?.backend_integration_url;
+}
+
+export function getMerchantConfigId(appBuilderUrl) {
+  try {
+    return new URL(appBuilderUrl).searchParams.get('merchantConfigId');
+  } catch (error) {
+    return null;
+  }
+}
+
+export function getOrderEntityId(orderData) {
+  return orderData?.id
+    ?? orderData?.entity_id
+    ?? orderData?.entityId;
+}
+
+function getDefaultOrigin() {
+  return typeof window !== 'undefined' ? window.location?.origin : undefined;
+}
+
+function getDefaultFetch() {
+  return typeof window !== 'undefined' ? window.fetch?.bind(window) : undefined;
+}
+
+export function getAbsoluteUrl(path, origin = getDefaultOrigin()) {
+  if (!origin) return path;
+  return new URL(path, origin).toString();
+}
+
+export function buildWorldpayPaymentPayload({
+  orderData,
+  returnUrl,
+  appBuilderUrl,
+  merchantConfigId = getMerchantConfigId(appBuilderUrl),
+  paymentMethod = WORLDPAY_PAYMENT_METHOD,
+}) {
+  const orderEntityId = getOrderEntityId(orderData);
+
+  if (!orderEntityId) {
+    throw new Error('Worldpay order entity id missing.');
+  }
+
+  return {
+    orderEntityId,
+    ...(merchantConfigId ? { merchantConfigId } : {}),
+    returnUrl,
+    paymentMethod,
+  };
+}
+
+export async function createWorldpayPayment({
+  appBuilderUrl,
+  orderData,
+  returnUrl,
+  merchantConfigId,
+  paymentMethod = WORLDPAY_PAYMENT_METHOD,
+  fetchImpl = getDefaultFetch(),
+}) {
+  if (!appBuilderUrl) {
+    throw new Error('Worldpay backend integration URL missing.');
+  }
+
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('Worldpay fetch implementation missing.');
+  }
+
+  const response = await fetchImpl(appBuilderUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(buildWorldpayPaymentPayload({
+      orderData,
+      returnUrl,
+      appBuilderUrl,
+      merchantConfigId,
+      paymentMethod,
+    })),
+  });
+
+  if (!response.ok) {
+    throw new Error('Worldpay payment creation failed.');
+  }
+
+  const data = await response.json();
+  const redirectUrl = data.redirectUrl ?? data.redirect_url;
+
+  if (!redirectUrl) {
+    throw new Error('Worldpay redirect URL missing.');
+  }
+
+  return {
+    redirectUrl,
+    data,
+  };
+}

package/src/checkout.js

@@ -0,0 +1,80 @@
+import { WORLDPAY_PAYMENT_METHOD, isWorldpayPaymentMethod } from './constants.js';
+import {
+  createWorldpayPayment,
+  getAbsoluteUrl,
+  getWorldpayBackendUrl,
+} from './app-builder-client.js';
+
+function getDefaultLocation() {
+  return typeof window !== 'undefined' ? window.location : undefined;
+}
+
+function getDefaultOrigin() {
+  return typeof window !== 'undefined' ? window.location?.origin : undefined;
+}
+
+export async function startWorldpayPayment({
+  cartData,
+  orderData,
+  returnUrl,
+  paymentMethodCode = WORLDPAY_PAYMENT_METHOD,
+  merchantConfigId,
+  fetchImpl,
+  locationRef = getDefaultLocation(),
+}) {
+  const appBuilderUrl = getWorldpayBackendUrl(cartData, paymentMethodCode);
+  const { redirectUrl, data } = await createWorldpayPayment({
+    appBuilderUrl,
+    orderData,
+    returnUrl,
+    merchantConfigId,
+    paymentMethod: WORLDPAY_PAYMENT_METHOD,
+    fetchImpl,
+  });
+
+  if (locationRef) {
+    locationRef.href = redirectUrl;
+  }
+
+  return {
+    redirectUrl,
+    data,
+  };
+}
+
+export async function handleWorldpayPlaceOrder({
+  cartId,
+  code,
+  cartData,
+  buildOrderUrl,
+  placeOrder,
+  merchantConfigId,
+  fetchImpl,
+  locationRef = getDefaultLocation(),
+  origin = getDefaultOrigin(),
+}) {
+  if (!isWorldpayPaymentMethod(code)) return false;
+
+  if (typeof buildOrderUrl !== 'function') {
+    throw new Error('Worldpay order URL builder missing.');
+  }
+
+  if (typeof placeOrder !== 'function') {
+    throw new Error('Worldpay place order function missing.');
+  }
+
+  const orderData = await placeOrder(cartId);
+  const returnUrl = getAbsoluteUrl(buildOrderUrl(orderData), origin);
+
+  await startWorldpayPayment({
+    cartData,
+    orderData,
+    returnUrl,
+    paymentMethodCode: code,
+    merchantConfigId,
+    fetchImpl,
+    locationRef,
+  });
+
+  return true;
+}

package/src/constants.js

@@ -0,0 +1,7 @@
+export const WORLDPAY_PAYMENT_METHOD = 'Worldpay';
+export const WORLDPAY_LOCAL_PAYMENT_METHOD_PREFIX = 'WorldpayLocal';
+
+export function isWorldpayPaymentMethod(code) {
+  return code === WORLDPAY_PAYMENT_METHOD
+    || String(code ?? '').startsWith(WORLDPAY_LOCAL_PAYMENT_METHOD_PREFIX);
+}

package/src/gql.js

@@ -0,0 +1,33 @@
+export const worldpayCheckoutGqlOperations = [
+  `
+    fragment AVAILABLE_PAYMENT_METHOD_FRAGMENT on AvailablePaymentMethod {
+      code
+      title
+      oope_payment_method_config {
+        backend_integration_url
+        custom_config {
+          ... on CustomConfigKeyValue {
+            key
+            value
+          }
+        }
+      }
+    }
+  `,
+  `
+    fragment SELECTED_PAYMENT_METHOD_FRAGMENT on SelectedPaymentMethod {
+      code
+      title
+      purchase_order_number
+      oope_payment_method_config {
+        backend_integration_url
+        custom_config {
+          ... on CustomConfigKeyValue {
+            key
+            value
+          }
+        }
+      }
+    }
+  `,
+];

package/src/index.js

@@ -0,0 +1,24 @@
+export {
+  WORLDPAY_LOCAL_PAYMENT_METHOD_PREFIX,
+  WORLDPAY_PAYMENT_METHOD,
+  isWorldpayPaymentMethod,
+} from './constants.js';
+export { worldpayCheckoutGqlOperations } from './gql.js';
+export {
+  transformPaymentMethod,
+  worldpayCheckoutModelTransformer,
+  worldpayOrderDataModelTransformer,
+} from './transformers.js';
+export {
+  buildWorldpayPaymentPayload,
+  createWorldpayPayment,
+  getAbsoluteUrl,
+  getMerchantConfigId,
+  getOrderEntityId,
+  getWorldpayBackendUrl,
+  getWorldpayMethodConfig,
+} from './app-builder-client.js';
+export {
+  handleWorldpayPlaceOrder,
+  startWorldpayPayment,
+} from './checkout.js';

package/src/order.js

@@ -0,0 +1 @@
+export { worldpayOrderDataModelTransformer } from './transformers.js';

package/src/transformers.js

@@ -0,0 +1,38 @@
+import { isWorldpayPaymentMethod } from './constants.js';
+
+export function transformPaymentMethod(method) {
+  if (!method) return method;
+
+  const { code, title, ...additionalData } = method;
+
+  return {
+    code,
+    title,
+    additionalData,
+  };
+}
+
+export function worldpayCheckoutModelTransformer(data) {
+  return {
+    availablePaymentMethods: data?.available_payment_methods
+      ?.map(transformPaymentMethod),
+    selectedPaymentMethod: transformPaymentMethod(
+      data?.selected_payment_method,
+    ),
+  };
+}
+
+export function worldpayOrderDataModelTransformer(data) {
+  const isWorldpay = data?.payment_methods?.some(
+    (method) => isWorldpayPaymentMethod(method?.type),
+  );
+  const status = String(data?.status ?? '').trim().toLowerCase();
+
+  if (isWorldpay && status === 'pending') {
+    return {
+      status: 'Pending Payment',
+    };
+  }
+
+  return {};
+}