@reactionary/commercetools 0.10.35 → 0.10.37

package/README.md

@@ -2,6 +2,28 @@
 
 This library was generated with [Nx](https://nx.dev).
 
+## Payment custom fields
+
+Payments created by `checkout.addPaymentInstruction` use the
+`reactionaryPaymentCustomFields` custom type, which must define:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `commerceToolsCartId` | String | The checkout (cart) the payment belongs to. |
+| `reactionaryProtocolData` | String | The payment's protocol channel, a JSON object exchanged with the payment extensions in both directions. |
+
+`reactionaryProtocolData` is how provider-specific payment data travels
+without reactionary knowing the provider:
+
+- **Inbound:** `addPaymentInstruction` writes the instruction's `protocolData`
+  into it (only when non-empty) — for example the delegated payment tokens of
+  UCP/ACP agents (`delegated_payment_token`, `ucp_payment_credential`).
+- **Outbound:** a payment API extension (e.g. the Stripe one) consumes the keys
+  it understands, then replaces the content with its results (e.g.
+  `stripe_clientSecret`, `stripe_status`), which also removes any token.
+- **Reading back:** the checkout factory flattens the JSON object into the
+  payment instruction's `protocolData` entries.
+
 ## Building
 
 Run `nx build commercetools` to build the library.

package/capabilities/checkout.capability.js

@@ -8,6 +8,7 @@ var __decorateClass = (decorators, target, key, kind) => {
   if (kind && result) __defProp(target, key, result);
   return result;
 };
+import { PROTOCOL_DATA_FIELD, serializeProtocolData } from "../core/payment-protocol-data.js";
 import {
   CheckoutMutationAddPaymentInstructionSchema,
   CheckoutMutationFinalizeCheckoutSchema,
@@ -164,16 +165,46 @@ class CommercetoolsCheckoutCapability extends CheckoutCapability {
   }
   async getAvailableShippingMethods(payload) {
     const client = await this.getClient();
-    const shippingMethodsResponse = await client.shippingMethods.matchingCart().get({
-      queryArgs: {
-        cartId: payload.checkout.key
-      }
-    }).execute();
+    const [shippingMethodsResponse, cartResponse] = await Promise.all([
+      client.shippingMethods.matchingCart().get({
+        queryArgs: {
+          cartId: payload.checkout.key
+        }
+      }).execute(),
+      client.carts.withId({ ID: payload.checkout.key }).get().execute()
+    ]);
     const result = shippingMethodsResponse.body.results.map(
-      (shippingMethod) => this.factory.parseShippingMethod(this.context, shippingMethod)
+      (shippingMethod) => this.factory.parseShippingMethod(this.context, this.withFreeShipping(shippingMethod, cartResponse.body))
     );
     return success(result);
   }
+  /**
+   * Quotes the matching shipping rates as free where the cart reaches the
+   * rate's free-above threshold. commercetools' matching-cart query returns
+   * the rates at their configured price and only applies the threshold once
+   * the method is set on the cart.
+   */
+  withFreeShipping(shippingMethod, cart) {
+    return {
+      ...shippingMethod,
+      zoneRates: shippingMethod.zoneRates.map((zoneRate) => ({
+        ...zoneRate,
+        shippingRates: zoneRate.shippingRates.map((rate) => rate.isMatching && this.isFreeShipping(rate, cart) ? { ...rate, price: { ...rate.price, centAmount: 0 } } : rate)
+      }))
+    };
+  }
+  /**
+   * Whether commercetools charges nothing for the rate once the method is set:
+   * shipping is free if the sum of the (custom) line item prices, after line
+   * item discounts, reaches the rate's free-above threshold.
+   */
+  isFreeShipping(rate, cart) {
+    if (!rate.freeAbove || rate.freeAbove.currencyCode !== cart.totalPrice.currencyCode) {
+      return false;
+    }
+    const itemsTotal = [...cart.lineItems, ...cart.customLineItems].reduce((sum, item) => sum + item.totalPrice.centAmount, 0);
+    return itemsTotal >= rate.freeAbove.centAmount;
+  }
   async getAvailablePaymentMethods(payload) {
     const staticMethods = this.getStaticPaymentMethods(payload.checkout);
     const dynamicMethods = [];
@@ -205,7 +236,10 @@ class CommercetoolsCheckoutCapability extends CheckoutCapability {
             key: "reactionaryPaymentCustomFields"
           },
           fields: {
-            commerceToolsCartId: payload.checkout.key
+            commerceToolsCartId: payload.checkout.key,
+            // Protocol data (e.g. agentic delegated payment tokens) is passed
+            // verbatim for the project's payment extensions to interpret.
+            ...payload.paymentInstruction.protocolData.length > 0 ? { [PROTOCOL_DATA_FIELD]: serializeProtocolData(payload.paymentInstruction.protocolData) } : {}
           }
         }
       }

package/core/payment-protocol-data.js

@@ -0,0 +1,26 @@
+const PROTOCOL_DATA_FIELD = "reactionaryProtocolData";
+function serializeProtocolData(entries) {
+  return JSON.stringify(Object.fromEntries(entries.map((entry) => [entry.key, entry.value])));
+}
+function parseProtocolDataField(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return [];
+    }
+    return Object.entries(parsed).map(([key, entry]) => ({
+      key,
+      value: typeof entry === "string" ? entry : JSON.stringify(entry)
+    }));
+  } catch {
+    return [];
+  }
+}
+export {
+  PROTOCOL_DATA_FIELD,
+  parseProtocolDataField,
+  serializeProtocolData
+};

package/factories/checkout/checkout.factory.js

@@ -1,3 +1,4 @@
+import { PROTOCOL_DATA_FIELD, parseProtocolDataField } from "../../core/payment-protocol-data.js";
 import {
   CheckoutItemSchema
 } from "@reactionary/core";
@@ -180,10 +181,9 @@ class CommercetoolsCheckoutFactory {
       name: paymentName || method || "Unknown"
     };
     const customData = data.custom?.fields || {};
-    const protocolData = Object.keys(customData).map((key) => ({
-      key,
-      value: customData[key]
-    }));
+    const protocolData = Object.keys(customData).flatMap(
+      (key) => key === PROTOCOL_DATA_FIELD ? parseProtocolDataField(customData[key]) : [{ key, value: customData[key] }]
+    );
     let status = "pending";
     if (data.transactions && data.transactions.length > 0) {
       const lastTransaction = data.transactions[data.transactions.length - 1];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/commercetools",
-  "version": "0.10.35",
+  "version": "0.10.37",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/Solteq/reactionary.git"
   },
   "dependencies": {
-    "@reactionary/core": "0.10.35",
+    "@reactionary/core": "0.10.37",
     "zod": "4.1.9",
     "@commercetools/ts-client": "^4.9.1",
     "@commercetools/platform-sdk": "^8.25.0",

package/src/capabilities/checkout.capability.d.ts

@@ -1,4 +1,4 @@
-import type { MyCartUpdateAction } from '@commercetools/platform-sdk';
+import type { Cart as CTCart, MyCartUpdateAction, ShippingMethod as CTShippingMethod, ShippingRate as CTShippingRate } from '@commercetools/platform-sdk';
 import type { Cache, CheckoutFactory, CheckoutFactoryCheckoutOutput, CheckoutFactoryPaymentMethodOutput, CheckoutFactoryShippingMethodOutput, CheckoutFactoryWithOutput, CheckoutIdentifier, CheckoutMutationAddPaymentInstruction, CheckoutMutationFinalizeCheckout, CheckoutMutationInitiateCheckout, CheckoutMutationRemovePaymentInstruction, CheckoutMutationSetShippingAddress, CheckoutMutationSetShippingInstruction, CheckoutQueryById, CheckoutQueryForAvailablePaymentMethods, CheckoutQueryForAvailableShippingMethods, NotFoundError, PaymentMethod, RequestContext, Result } from '@reactionary/core';
 import { CheckoutCapability } from '@reactionary/core';
 import type { CommercetoolsAPI } from '../core/client.js';
@@ -23,6 +23,19 @@ export declare class CommercetoolsCheckoutCapability<TFactory extends CheckoutFa
     getById(payload: CheckoutQueryById): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>, NotFoundError>>;
     setShippingAddress(payload: CheckoutMutationSetShippingAddress): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
     getAvailableShippingMethods(payload: CheckoutQueryForAvailableShippingMethods): Promise<Result<CheckoutFactoryShippingMethodOutput<TFactory>[]>>;
+    /**
+     * Quotes the matching shipping rates as free where the cart reaches the
+     * rate's free-above threshold. commercetools' matching-cart query returns
+     * the rates at their configured price and only applies the threshold once
+     * the method is set on the cart.
+     */
+    protected withFreeShipping(shippingMethod: CTShippingMethod, cart: CTCart): CTShippingMethod;
+    /**
+     * Whether commercetools charges nothing for the rate once the method is set:
+     * shipping is free if the sum of the (custom) line item prices, after line
+     * item discounts, reaches the rate's free-above threshold.
+     */
+    protected isFreeShipping(rate: CTShippingRate, cart: CTCart): boolean;
     getAvailablePaymentMethods(payload: CheckoutQueryForAvailablePaymentMethods): Promise<Result<CheckoutFactoryPaymentMethodOutput<TFactory>[]>>;
     addPaymentInstruction(payload: CheckoutMutationAddPaymentInstruction): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
     removePaymentInstruction(payload: CheckoutMutationRemovePaymentInstruction): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;

package/src/core/payment-protocol-data.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A payment's protocol channel: one JSON custom field on the
+ * `reactionaryPaymentCustomFields` type, exchanged in both directions with the
+ * project's payment API extensions. reactionary writes a payment instruction's
+ * protocol data into it; extensions consume what they understand (e.g. agent
+ * payment tokens) and write their results back (e.g. a Stripe client secret).
+ * One declared field carries arbitrary keys, which separate custom fields could
+ * not: commercetools rejects undeclared fields.
+ */
+export declare const PROTOCOL_DATA_FIELD = "reactionaryProtocolData";
+export declare function serializeProtocolData(entries: Array<{
+    key: string;
+    value: string;
+}>): string;
+export declare function parseProtocolDataField(value: unknown): Array<{
+    key: string;
+    value: string;
+}>;