@reactionary/commercetools 0.10.35 → 0.10.36

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,
@@ -205,7 +206,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.36",
   "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.36",
     "zod": "4.1.9",
     "@commercetools/ts-client": "^4.9.1",
     "@commercetools/platform-sdk": "^8.25.0",

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;
+}>;