@reactionary/medusa 0.10.54 → 0.10.55

package/capabilities/checkout.capability.js

@@ -61,17 +61,17 @@ class MedusaCheckoutCapability extends CheckoutCapability {
    *
    * example: this.includedFields = [includedFields, '+discounts.*'].join(',');
    */
-  includedFields = ["+items.*", "+order.id", "+order.display_id", "+order.custom_display_id"].join(",");
+  includedFields = ["+items.*", "+order.id", "+order.display_id", "+order.custom_display_id", "+shipping_methods.data"].join(",");
   /**
    * This controls which fields are requested for the cart's shipping options.
    * You can override this in a subclass to add more fields as needed.
    *
    * The service zone's fulfillment set tells us whether an option is in-store
-   * pickup (BOPIS) or a delivery, and the option metadata lets medusa-side
-   * providers push additional data that is mapped to the shipping method's
-   * protocolData.
+   * pickup (BOPIS) or a delivery, and the option data is the fulfillment
+   * provider's payload (e.g. nShift option/carrier ids) that is mapped to the
+   * shipping method's protocolData.
    */
-  shippingOptionFields = ["*service_zone.fulfillment_set", "+metadata"].join(",");
+  shippingOptionFields = ["*service_zone.fulfillment_set", "+data"].join(",");
   initiateCheckoutForCartPayload(payload) {
     return {
       billing_address: payload.billingAddress ? this.mapAddressToStoreAddress(payload.billingAddress) : void 0,
@@ -276,12 +276,19 @@ class MedusaCheckoutCapability extends CheckoutCapability {
     throw new Error("Method not implemented.");
   }
   setShippingInstructionPayload(payload) {
+    const data = {
+      consent_for_unattended_delivery: payload.shippingInstruction.consentForUnattendedDelivery + "",
+      instructions: payload.shippingInstruction.instructions || ""
+    };
+    for (const entry of payload.shippingInstruction.protocolData ?? []) {
+      data[entry.key] = entry.value;
+    }
+    if (payload.shippingInstruction.pickupPoint) {
+      data["pickup_point"] = payload.shippingInstruction.pickupPoint;
+    }
     return {
       option_id: payload.shippingInstruction.shippingMethod.key,
-      data: {
-        consent_for_unattended_delivery: payload.shippingInstruction.consentForUnattendedDelivery + "",
-        instructions: payload.shippingInstruction.instructions || ""
-      }
+      data
     };
   }
   /**

package/factories/checkout/checkout.factory.js

@@ -3,6 +3,7 @@ import {
 import {
   AddressIdentifierSchema,
   MonetaryAmountSchema,
+  SHIPPING_PROTOCOL_DATA_KEYS,
   ShippingMethodIdentifierSchema
 } from "@reactionary/core";
 import {
@@ -121,7 +122,7 @@ class MedusaCheckoutFactory {
         instructions = sm.data["instructions"] != null ? String(sm.data["instructions"]) : "";
         consentForUnattendedDelivery = sm.data["consent_for_unattended_delivery"] === "true";
         pickupStore = sm.data["pickup_store"] != null && sm.data["pickup_store"] !== "" ? String(sm.data["pickup_store"]) : void 0;
-        protocolData = this.parseShippingProtocolData(sm.data["shipping_protocol_data"]);
+        protocolData = this.parseInstructionProtocolData(sm.data);
       }
       if (!pickupPoint) {
         pickupPoint = backupPickupPoint || "";
@@ -209,11 +210,46 @@ class MedusaCheckoutFactory {
         currency: data.calculated_price.currency_code?.toUpperCase() || _context.languageContext.currencyCode
       }),
       deliveryTime: "",
+      carrier: this.parseShippingMethodCarrier(_context, data),
       fulfillmentType: this.parseFulfillmentType(_context, data),
-      protocolData: this.parseShippingMethodProtocolData(_context, data)
+      protocolData: this.mergeShippingMethodProtocolData(
+        this.parseShippingMethodProtocolData(_context, data),
+        this.parseShippingMethodStoreReference(_context, data)
+      )
     };
     return this.shippingMethodSchema.parse(sm);
   }
+  /**
+   * Appends a conventional entry to the provider-derived protocol data,
+   * unless the provider data already carries the same key (explicit provider
+   * data wins).
+   */
+  mergeShippingMethodProtocolData(protocolData, entry) {
+    if (!entry) {
+      return protocolData;
+    }
+    if ((protocolData ?? []).some((existing) => existing.key === entry.key)) {
+      return protocolData;
+    }
+    return [...protocolData ?? [], entry];
+  }
+  /**
+   * Extension point emitting the conventional "pickup_store" protocol data
+   * entry for in-store pickup options: the stock location id of the service
+   * zone's fulfillment set, which equals the store capability's
+   * Store.identifier.key. Delivery options also carry a location (the
+   * warehouse), so the entry is emitted for pickup options only.
+   */
+  parseShippingMethodStoreReference(_context, data) {
+    if (this.parseFulfillmentType(_context, data) !== "pickup") {
+      return void 0;
+    }
+    const locationId = data.service_zone?.fulfillment_set?.location?.id;
+    if (!locationId) {
+      return void 0;
+    }
+    return { key: SHIPPING_PROTOCOL_DATA_KEYS.pickupStore, value: locationId };
+  }
   /**
    * Extension point to control how a Medusa shipping option maps to the core
    * fulfillment type. A shipping option belonging to a fulfillment set of type
@@ -223,18 +259,33 @@ class MedusaCheckoutFactory {
     return data.service_zone?.fulfillment_set?.type === "pickup" ? "pickup" : "delivery";
   }
   /**
-   * Extension point mapping a Medusa shipping option's metadata to the
-   * shipping method's protocolData, so medusa-side providers can push
-   * additional data (e.g. available pickup time slots) that reaches the
-   * client. String and JSON-object values are kept as-is, other primitives
-   * are stringified, and arrays/null entries are skipped.
+   * Extension point mapping a Medusa shipping option's `data` - the payload
+   * the fulfillment provider works with (e.g. nShift's option/carrier ids) -
+   * to the shipping method's protocolData, so provider-protocol data reaches
+   * the client. String and JSON-object values are kept as-is, other
+   * primitives are stringified, and arrays/null entries are skipped.
+   *
+   * Option `metadata` is deliberately NOT mapped: it is merchant free-form
+   * annotation, not protocol data. Override this hook to surface it.
    */
   parseShippingMethodProtocolData(_context, data) {
-    if (!data.metadata) {
+    if (!data.data) {
       return void 0;
     }
+    const entries = this.convertToProtocolDataEntries(data.data);
+    return entries.length > 0 ? entries : void 0;
+  }
+  /**
+   * Converts a Medusa key-value record into protocol data entries: string and
+   * JSON-object values are kept as-is, other primitives are stringified, and
+   * arrays/null entries are skipped. Keys listed in skipKeys are left out.
+   */
+  convertToProtocolDataEntries(record, skipKeys = []) {
     const entries = [];
-    for (const [key, value] of Object.entries(data.metadata)) {
+    for (const [key, value] of Object.entries(record)) {
+      if (skipKeys.includes(key)) {
+        continue;
+      }
       if (typeof value === "string") {
         entries.push({ key, value });
       } else if (typeof value === "number" || typeof value === "boolean") {
@@ -243,6 +294,49 @@ class MedusaCheckoutFactory {
         entries.push({ key, value });
       }
     }
+    return entries;
+  }
+  /**
+   * Extension point resolving the carrier of a shipping option from its
+   * provider data (e.g. nShift's carrier_id), when present.
+   */
+  parseShippingMethodCarrier(_context, data) {
+    const carrierId = data.data?.["carrier_id"];
+    return typeof carrierId === "string" && carrierId.length > 0 ? carrierId : void 0;
+  }
+  /**
+   * The persisted shipping method data keys that are NOT surfaced as
+   * instruction protocol data: keys already represented as first-class
+   * instruction fields, the legacy JSON blob, and provider-side values that
+   * would mislead (nShift's data.price is not the charged amount).
+   */
+  instructionProtocolDataSkipKeys = [
+    "pickup_store",
+    "pickup_point",
+    "instructions",
+    "consent_for_unattended_delivery",
+    "shipping_protocol_data",
+    "price",
+    "currency_code"
+  ];
+  /**
+   * Builds the shipping instruction's protocolData from the persisted
+   * shipping method data: the provider payload enriched by the backend (e.g.
+   * nShift's session_id, carrier ids and optional delivery_time) merged with
+   * whatever the client sent when setting the instruction. First-class and
+   * misleading keys are skipped; the legacy shipping_protocol_data JSON blob
+   * still contributes entries whose keys are not already present.
+   */
+  parseInstructionProtocolData(smData) {
+    const entries = this.convertToProtocolDataEntries(
+      smData,
+      this.instructionProtocolDataSkipKeys
+    );
+    for (const legacyEntry of this.parseShippingProtocolData(smData["shipping_protocol_data"]) ?? []) {
+      if (!entries.some((entry) => entry.key === legacyEntry.key)) {
+        entries.push(legacyEntry);
+      }
+    }
     return entries.length > 0 ? entries : void 0;
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/medusa",
-  "version": "0.10.54",
+  "version": "0.10.55",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@medusajs/js-sdk": "^2.13.3",
-    "@reactionary/core": "0.10.54",
+    "@reactionary/core": "0.10.55",
     "debug": "^4.4.3",
     "@medusajs/types": "^2.13.3",
     "zod": "4.1.9"

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

@@ -25,9 +25,9 @@ export declare class MedusaCheckoutCapability<TFactory extends CheckoutFactory =
      * You can override this in a subclass to add more fields as needed.
      *
      * The service zone's fulfillment set tells us whether an option is in-store
-     * pickup (BOPIS) or a delivery, and the option metadata lets medusa-side
-     * providers push additional data that is mapped to the shipping method's
-     * protocolData.
+     * pickup (BOPIS) or a delivery, and the option data is the fulfillment
+     * provider's payload (e.g. nShift option/carrier ids) that is mapped to the
+     * shipping method's protocolData.
      */
     protected shippingOptionFields: string;
     constructor(config: MedusaConfiguration, cache: Cache, context: RequestContext, medusaApi: MedusaAPI, factory: CheckoutFactoryWithOutput<TFactory>);

package/src/factories/checkout/checkout.factory.d.ts

@@ -45,6 +45,20 @@ export declare class MedusaCheckoutFactory<TCheckoutSchema extends AnyCheckoutSc
     protected isCart(data: StoreCart): data is StoreCart;
     parseCheckout(context: RequestContext, data: StoreCart): z.output<TCheckoutSchema>;
     parseShippingMethod(_context: RequestContext, data: MedusaShippingOptionWithMetadata): z.output<TShippingMethodSchema>;
+    /**
+     * Appends a conventional entry to the provider-derived protocol data,
+     * unless the provider data already carries the same key (explicit provider
+     * data wins).
+     */
+    protected mergeShippingMethodProtocolData(protocolData: ShippingProtocolData[] | undefined, entry: ShippingProtocolData | undefined): ShippingProtocolData[] | undefined;
+    /**
+     * Extension point emitting the conventional "pickup_store" protocol data
+     * entry for in-store pickup options: the stock location id of the service
+     * zone's fulfillment set, which equals the store capability's
+     * Store.identifier.key. Delivery options also carry a location (the
+     * warehouse), so the entry is emitted for pickup options only.
+     */
+    protected parseShippingMethodStoreReference(_context: RequestContext, data: MedusaShippingOptionWithMetadata): ShippingProtocolData | undefined;
     /**
      * Extension point to control how a Medusa shipping option maps to the core
      * fulfillment type. A shipping option belonging to a fulfillment set of type
@@ -52,13 +66,43 @@ export declare class MedusaCheckoutFactory<TCheckoutSchema extends AnyCheckoutSc
      */
     protected parseFulfillmentType(_context: RequestContext, data: MedusaShippingOptionWithMetadata): ShippingFulfillmentType;
     /**
-     * Extension point mapping a Medusa shipping option's metadata to the
-     * shipping method's protocolData, so medusa-side providers can push
-     * additional data (e.g. available pickup time slots) that reaches the
-     * client. String and JSON-object values are kept as-is, other primitives
-     * are stringified, and arrays/null entries are skipped.
+     * Extension point mapping a Medusa shipping option's `data` - the payload
+     * the fulfillment provider works with (e.g. nShift's option/carrier ids) -
+     * to the shipping method's protocolData, so provider-protocol data reaches
+     * the client. String and JSON-object values are kept as-is, other
+     * primitives are stringified, and arrays/null entries are skipped.
+     *
+     * Option `metadata` is deliberately NOT mapped: it is merchant free-form
+     * annotation, not protocol data. Override this hook to surface it.
      */
     protected parseShippingMethodProtocolData(_context: RequestContext, data: MedusaShippingOptionWithMetadata): ShippingProtocolData[] | undefined;
+    /**
+     * Converts a Medusa key-value record into protocol data entries: string and
+     * JSON-object values are kept as-is, other primitives are stringified, and
+     * arrays/null entries are skipped. Keys listed in skipKeys are left out.
+     */
+    protected convertToProtocolDataEntries(record: Record<string, unknown>, skipKeys?: readonly string[]): ShippingProtocolData[];
+    /**
+     * Extension point resolving the carrier of a shipping option from its
+     * provider data (e.g. nShift's carrier_id), when present.
+     */
+    protected parseShippingMethodCarrier(_context: RequestContext, data: MedusaShippingOptionWithMetadata): string | undefined;
+    /**
+     * The persisted shipping method data keys that are NOT surfaced as
+     * instruction protocol data: keys already represented as first-class
+     * instruction fields, the legacy JSON blob, and provider-side values that
+     * would mislead (nShift's data.price is not the charged amount).
+     */
+    protected instructionProtocolDataSkipKeys: readonly string[];
+    /**
+     * Builds the shipping instruction's protocolData from the persisted
+     * shipping method data: the provider payload enriched by the backend (e.g.
+     * nShift's session_id, carrier ids and optional delivery_time) merged with
+     * whatever the client sent when setting the instruction. First-class and
+     * misleading keys are skipped; the legacy shipping_protocol_data JSON blob
+     * still contributes entries whose keys are not already present.
+     */
+    protected parseInstructionProtocolData(smData: Record<string, unknown>): ShippingProtocolData[] | undefined;
     /**
      * Parses shipping protocol data persisted as a JSON object string (keys
      * mapping to string or JSON-object values) back into protocol data entries.