@reactionary/magento 0.10.26 → 0.10.27

package/capabilities/checkout.capability.js

@@ -32,6 +32,36 @@ import {
   encodeShippingMethodKey
 } from "../factories/checkout/checkout.factory.js";
 const debug = createDebug("reactionary:magento:checkout");
+function nonEmptyString(value) {
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function numberValue(value) {
+  return typeof value === "number" ? value : void 0;
+}
+function parseQuoteAddress(raw) {
+  const rawStreet = raw["street"];
+  const street = Array.isArray(rawStreet) ? rawStreet.filter((line) => nonEmptyString(line) !== void 0) : [];
+  const firstname = nonEmptyString(raw["firstname"]);
+  const city = nonEmptyString(raw["city"]);
+  if (!firstname || !city || street.length === 0) {
+    return void 0;
+  }
+  return {
+    firstname,
+    lastname: nonEmptyString(raw["lastname"]),
+    street,
+    city,
+    company: nonEmptyString(raw["company"]),
+    region: nonEmptyString(raw["region"]),
+    region_id: numberValue(raw["region_id"]),
+    region_code: nonEmptyString(raw["region_code"]),
+    customer_address_id: numberValue(raw["customer_address_id"]),
+    postcode: nonEmptyString(raw["postcode"]),
+    country_id: nonEmptyString(raw["country_id"]),
+    telephone: nonEmptyString(raw["telephone"]),
+    email: nonEmptyString(raw["email"])
+  };
+}
 class CheckoutNotReadyForFinalizationError extends Error {
   constructor(checkoutIdentifier) {
     super(
@@ -77,6 +107,68 @@ class MagentoCheckoutCapability extends CheckoutCapability {
     }
     return { cart, totals };
   }
+  /**
+   * The quote's `billing_address` is the only checkout data Magento keeps
+   * durably before an order is placed, so it is where email and address
+   * survive between requests. Never throws: a missing quote simply yields
+   * nothing to fall back to.
+   */
+  async readQuoteBillingAddress(cartKey) {
+    try {
+      const cart = await this.magentoApi.getCart(cartKey);
+      const raw = cart.billing_address;
+      if (!raw) {
+        return {};
+      }
+      return {
+        email: nonEmptyString(raw["email"]),
+        countryId: nonEmptyString(raw["country_id"]),
+        address: parseQuoteAddress(raw)
+      };
+    } catch (err) {
+      debug("Failed to read billing address from quote: %O", err);
+      return {};
+    }
+  }
+  /**
+   * Loads the session checkout state and, when this request's session does
+   * not know the email or billing address (e.g. every request in a web
+   * storefront starts with an empty session), rebuilds them from the quote.
+   */
+  async loadCheckoutState(cartKey) {
+    const state = await this.magentoApi.getCheckoutState(cartKey);
+    if (!state.email || !state.billingAddress) {
+      const quote = await this.readQuoteBillingAddress(cartKey);
+      state.email = state.email || quote.email;
+      state.billingAddress = state.billingAddress ?? quote.address;
+    }
+    return state;
+  }
+  async persistBillingAddressOnQuote(cartKey, address) {
+    try {
+      await this.magentoApi.setCheckoutBillingAddress(cartKey, address);
+    } catch (err) {
+      debug("Failed to persist billing address on quote: %O", err);
+    }
+  }
+  /**
+   * Stores the email on the quote before any address is known. Magento only
+   * accepts a billing address with a country, so this reuses the country the
+   * quote already carries (Magento pre-fills the store's default country)
+   * rather than inventing one; without it the email stays session-only.
+   */
+  async persistEmailOnQuote(cartKey, state) {
+    let address = state.billingAddress;
+    if (!address) {
+      const { countryId } = await this.readQuoteBillingAddress(cartKey);
+      address = countryId ? { country_id: countryId } : void 0;
+    }
+    if (!address) {
+      debug("Quote has no country; email for %s is kept in the session only", cartKey);
+      return;
+    }
+    await this.persistBillingAddressOnQuote(cartKey, { ...address, email: state.email });
+  }
   async buildCheckout(cartKey, state) {
     const { cart, totals } = await this.loadCartAndTotals(cartKey);
     const data = {
@@ -89,20 +181,17 @@ class MagentoCheckoutCapability extends CheckoutCapability {
   }
   async initiateCheckoutForCart(payload) {
     const cartKey = payload.cart.identifier.key;
-    const state = await this.magentoApi.getCheckoutState(cartKey);
+    const state = await this.loadCheckoutState(cartKey);
     state.email = payload.notificationEmail ?? state.email;
     state.phone = payload.notificationPhone ?? state.phone;
     if (payload.billingAddress) {
-      const billingAddress = this.toMagentoAddress(
+      state.billingAddress = this.toMagentoAddress(
         payload.billingAddress,
         state.email
       );
-      state.billingAddress = billingAddress;
-      try {
-        await this.magentoApi.setCheckoutBillingAddress(cartKey, billingAddress);
-      } catch (err) {
-        debug("Failed to persist billing address on quote: %O", err);
-      }
+      await this.persistBillingAddressOnQuote(cartKey, state.billingAddress);
+    } else if (payload.notificationEmail) {
+      await this.persistEmailOnQuote(cartKey, state);
     }
     await this.magentoApi.setCheckoutState(cartKey, state);
     return success(await this.buildCheckout(cartKey, state));
@@ -110,7 +199,7 @@ class MagentoCheckoutCapability extends CheckoutCapability {
   async getById(payload) {
     const cartKey = payload.identifier.key;
     try {
-      const state = await this.magentoApi.getCheckoutState(cartKey);
+      const state = await this.loadCheckoutState(cartKey);
       return success(await this.buildCheckout(cartKey, state));
     } catch (err) {
       debug("Failed to load checkout: %O", err);
@@ -122,17 +211,18 @@ class MagentoCheckoutCapability extends CheckoutCapability {
   }
   async setShippingAddress(payload) {
     const cartKey = payload.checkout.key;
-    const state = await this.magentoApi.getCheckoutState(cartKey);
+    const state = await this.loadCheckoutState(cartKey);
     state.shippingAddress = this.toMagentoAddress(
       payload.shippingAddress,
       state.email
     );
+    await this.persistBillingAddressOnQuote(cartKey, state.shippingAddress);
     await this.magentoApi.setCheckoutState(cartKey, state);
     return success(await this.buildCheckout(cartKey, state));
   }
   async getAvailableShippingMethods(payload) {
     const cartKey = payload.checkout.key;
-    const state = await this.magentoApi.getCheckoutState(cartKey);
+    const state = await this.loadCheckoutState(cartKey);
     const address = state.shippingAddress || state.billingAddress;
     if (!address) {
       return success([]);
@@ -151,7 +241,7 @@ class MagentoCheckoutCapability extends CheckoutCapability {
   }
   async addPaymentInstruction(payload) {
     const cartKey = payload.checkout.key;
-    const state = await this.magentoApi.getCheckoutState(cartKey);
+    const state = await this.loadCheckoutState(cartKey);
     const instruction = {
       key: `pi_${Date.now()}`,
       method: payload.paymentInstruction.paymentMethod.method,
@@ -171,7 +261,7 @@ class MagentoCheckoutCapability extends CheckoutCapability {
   }
   async removePaymentInstruction(payload) {
     const cartKey = payload.checkout.key;
-    const state = await this.magentoApi.getCheckoutState(cartKey);
+    const state = await this.loadCheckoutState(cartKey);
     state.paymentInstructions = (state.paymentInstructions ?? []).filter(
       (pi) => pi.key !== payload.paymentInstruction.key
     );
@@ -180,7 +270,7 @@ class MagentoCheckoutCapability extends CheckoutCapability {
   }
   async setShippingInstruction(payload) {
     const cartKey = payload.checkout.key;
-    const state = await this.magentoApi.getCheckoutState(cartKey);
+    const state = await this.loadCheckoutState(cartKey);
     const address = state.shippingAddress || state.billingAddress;
     if (!address) {
       return error({
@@ -220,23 +310,45 @@ class MagentoCheckoutCapability extends CheckoutCapability {
   }
   async finalizeCheckout(payload) {
     const cartKey = payload.checkout.key;
-    const state = await this.magentoApi.getCheckoutState(cartKey);
+    const state = await this.loadCheckoutState(cartKey);
+    if (state.orderId) {
+      return success(await this.buildOrderedCheckout(cartKey, state));
+    }
     const paymentInstruction = state.paymentInstructions?.[0];
     if (!paymentInstruction || !state.shippingInstruction) {
       throw new CheckoutNotReadyForFinalizationError(payload.checkout);
     }
     const orderId = await this.magentoApi.placeOrder(cartKey, {
       email: state.email,
-      paymentMethod: {
-        method: paymentInstruction.method
-      },
+      paymentMethod: this.toMagentoPaymentMethod(paymentInstruction),
       billingAddress: state.billingAddress
     });
     state.orderId = String(orderId);
     await this.magentoApi.setCheckoutState(cartKey, state);
     await this.magentoApi.clearActiveCartId();
+    return success(await this.buildOrderedCheckout(cartKey, state));
+  }
+  /**
+   * Forwards the payment instruction's protocol data (e.g. a PSP transaction
+   * id) as Magento's `additional_data`, which payment methods read on placement,
+   * and the configured terms and conditions ids as `agreement_ids`, without
+   * which stores with terms and conditions enabled reject the order.
+   */
+  toMagentoPaymentMethod(instruction) {
+    const payload = { method: instruction.method };
+    if (instruction.protocolData.length > 0) {
+      payload.additional_data = Object.fromEntries(
+        instruction.protocolData.map(({ key, value }) => [key, value])
+      );
+    }
+    if (this.config.checkoutAgreementIds) {
+      payload.extension_attributes = { agreement_ids: this.config.checkoutAgreementIds };
+    }
+    return payload;
+  }
+  async buildOrderedCheckout(cartKey, state) {
     try {
-      return success(await this.buildCheckout(cartKey, state));
+      return await this.buildCheckout(cartKey, state);
     } catch (err) {
       debug("Cart no longer retrievable after order placement: %O", err);
       const data = {
@@ -244,7 +356,7 @@ class MagentoCheckoutCapability extends CheckoutCapability {
         state,
         requestedKey: cartKey
       };
-      return success(this.factory.parseCheckout(this.context, data));
+      return this.factory.parseCheckout(this.context, data);
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/magento",
-  "version": "0.10.26",
+  "version": "0.10.27",
   "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.26",
+    "@reactionary/core": "0.10.27",
     "zod": "4.1.9",
     "debug": "^4.4.3"
   },

package/schema/configuration.schema.js

@@ -10,6 +10,7 @@ const MagentoConfigurationSchema = z.looseObject({
   graphqlUrl: z.string().optional().meta({ description: "The GraphQL endpoint. Defaults to `{baseUrl}/graphql`. Reviews and ratings have no REST equivalent in Magento, so the product reviews capability goes through GraphQL." }),
   reviewRatingCode: z.string().optional().meta({ description: 'The name of the Magento review rating (as listed by `productReviewRatingsMetadata`) that carries the overall star rating. Defaults to "Rating"; the first available rating is used as a fallback.' }),
   storeCode: z.string().default(""),
+  checkoutAgreementIds: z.array(z.string()).optional().meta({ description: "Ids of the Magento terms and conditions (Magento_CheckoutAgreements) the shopper accepts when placing an order. Required by stores with \"Enable Terms and Conditions\" on, which otherwise reject order placement. Sent as the payment method's `extension_attributes.agreement_ids`. The storefront must collect the shopper's consent before finalizing checkout." }),
   authStoreCode: z.string().default("default").meta({ description: "The store/website scope used for customer authentication and account operations (token, customers/me). Customers typically live on the default website, which may differ from the catalog storeCode." })
 });
 export {

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

@@ -2,7 +2,7 @@ import { CheckoutCapability, type Address, type Cache, type CheckoutFactory, typ
 import type { MagentoClient } from '../core/client.js';
 import { type MagentoCheckoutFactory } from '../factories/checkout/checkout.factory.js';
 import type { MagentoConfiguration } from '../schema/configuration.schema.js';
-import type { MagentoCart, MagentoCartTotals, MagentoCheckoutAddress, MagentoCheckoutState } from '../schema/magento.types.js';
+import type { MagentoCart, MagentoCartTotals, MagentoCheckoutAddress, MagentoCheckoutState, MagentoPaymentMethodPayload, MagentoStoredPaymentInstruction } from '../schema/magento.types.js';
 export declare class CheckoutNotReadyForFinalizationError extends Error {
     checkoutIdentifier: CheckoutIdentifier;
     constructor(checkoutIdentifier: CheckoutIdentifier);
@@ -17,6 +17,31 @@ export declare class MagentoCheckoutCapability<TFactory extends CheckoutFactory
         cart: MagentoCart;
         totals?: MagentoCartTotals;
     }>;
+    /**
+     * The quote's `billing_address` is the only checkout data Magento keeps
+     * durably before an order is placed, so it is where email and address
+     * survive between requests. Never throws: a missing quote simply yields
+     * nothing to fall back to.
+     */
+    protected readQuoteBillingAddress(cartKey: string): Promise<{
+        email?: string;
+        countryId?: string;
+        address?: MagentoCheckoutAddress;
+    }>;
+    /**
+     * Loads the session checkout state and, when this request's session does
+     * not know the email or billing address (e.g. every request in a web
+     * storefront starts with an empty session), rebuilds them from the quote.
+     */
+    protected loadCheckoutState(cartKey: string): Promise<MagentoCheckoutState>;
+    protected persistBillingAddressOnQuote(cartKey: string, address: MagentoCheckoutAddress): Promise<void>;
+    /**
+     * Stores the email on the quote before any address is known. Magento only
+     * accepts a billing address with a country, so this reuses the country the
+     * quote already carries (Magento pre-fills the store's default country)
+     * rather than inventing one; without it the email stays session-only.
+     */
+    protected persistEmailOnQuote(cartKey: string, state: MagentoCheckoutState): Promise<void>;
     protected buildCheckout(cartKey: string, state: MagentoCheckoutState): Promise<CheckoutFactoryCheckoutOutput<TFactory>>;
     initiateCheckoutForCart(payload: CheckoutMutationInitiateCheckout): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
     getById(payload: CheckoutQueryById): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>, NotFoundError>>;
@@ -27,4 +52,12 @@ export declare class MagentoCheckoutCapability<TFactory extends CheckoutFactory
     removePaymentInstruction(payload: CheckoutMutationRemovePaymentInstruction): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
     setShippingInstruction(payload: CheckoutMutationSetShippingInstruction): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
     finalizeCheckout(payload: CheckoutMutationFinalizeCheckout): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
+    /**
+     * Forwards the payment instruction's protocol data (e.g. a PSP transaction
+     * id) as Magento's `additional_data`, which payment methods read on placement,
+     * and the configured terms and conditions ids as `agreement_ids`, without
+     * which stores with terms and conditions enabled reject the order.
+     */
+    protected toMagentoPaymentMethod(instruction: MagentoStoredPaymentInstruction): MagentoPaymentMethodPayload;
+    protected buildOrderedCheckout(cartKey: string, state: MagentoCheckoutState): Promise<CheckoutFactoryCheckoutOutput<TFactory>>;
 }

package/src/index.d.ts

@@ -1,6 +1,7 @@
 export * from './schema/configuration.schema.js';
 export * from './schema/capabilities.schema.js';
 export * from './schema/magento.schema.js';
+export type { MagentoCategory, MagentoCheckoutAddress, MagentoCheckoutState, MagentoCustomAttribute, MagentoProduct, MagentoProductSearchResult, } from './schema/magento.types.js';
 export * from './core/initialize.js';
 export * from './core/initialize.types.js';
 export * from './core/client.js';

package/src/schema/configuration.schema.d.ts

@@ -13,6 +13,7 @@ export declare const MagentoConfigurationSchema: z.ZodObject<{
     graphqlUrl: z.ZodOptional<z.ZodString>;
     reviewRatingCode: z.ZodOptional<z.ZodString>;
     storeCode: z.ZodDefault<z.ZodString>;
+    checkoutAgreementIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     authStoreCode: z.ZodDefault<z.ZodString>;
 }, z.core.$loose>;
 export type MagentoConfiguration = z.infer<typeof MagentoConfigurationSchema>;

package/src/schema/magento.types.d.ts

@@ -228,6 +228,7 @@ export interface MagentoCheckoutAddress {
     email?: string;
     same_as_billing?: number;
     save_in_address_book?: number;
+    customer_address_id?: number;
 }
 export interface MagentoShippingMethod {
     carrier_code: string;
@@ -277,6 +278,9 @@ export interface MagentoPaymentMethodPayload {
     method: string;
     po_number?: string;
     additional_data?: Record<string, string> | string[];
+    extension_attributes?: {
+        agreement_ids?: string[];
+    };
 }
 export interface MagentoPlaceOrderPayload {
     email?: string;