@reactionary/medusa 0.10.50 → 0.10.52

package/capabilities/cart.capability.js

@@ -28,8 +28,11 @@ import {
   Reactionary,
   success
 } from "@reactionary/core";
+import { FetchError } from "@medusajs/js-sdk";
 import {} from "@medusajs/types";
 import createDebug from "debug";
+import { MedusaAdminAPI } from "../core/client.js";
+import { MedusaCachedPluginListSchema } from "../schema/medusa.schema.js";
 import {
   handleProviderError
 } from "../utils/medusa-helpers.js";
@@ -51,7 +54,87 @@ class MedusaCartCapability extends CartCapability {
    * example: this.includedFields = [includedFields, '+discounts.*'].join(',');
    */
   includedFields = ["+items.*", "+items.adjustments.*", "+shipping_methods.adjustments.*"].join(",");
+  /**
+   * Fields requested when listing owned carts, both via the cart-ownership
+   * endpoint and via the session-tracked fallback. Every entry must be in
+   * the allowed field set of both routes; `customer.id` stands in for
+   * `customer_id`, which is not an allowed field (see normalizeOwnedCart).
+   */
+  ownedCartListFields = ["id", "updated_at", "metadata", "items.id", "customer.id"].join(",");
+  /** Sort order for the server-side owned-carts listing. */
+  ownedCartListOrder = "-updated_at";
+  /**
+   * Package name of the optional backend plugin that serves
+   * `GET /store/customers/me/carts` (a logged-in customer's open carts).
+   */
+  cartOwnershipPluginName = "@solteq-excom/medusa-cart-ownership";
+  /**
+   * How long a backend's plugin list stays cached. Bounds how late a newly
+   * (un)installed cart-ownership plugin is noticed.
+   */
+  pluginDetectionTtlSeconds = 900;
   async listCarts(payload) {
+    let data = null;
+    if (await this.shouldUseOwnershipEndpoint(payload)) {
+      data = await this.listCartsViaOwnershipEndpoint(payload);
+    }
+    data ??= await this.listCartsFromSession(payload);
+    return success(this.factory.parseCartPaginatedSearchResult(this.context, data, payload));
+  }
+  /**
+   * The server-side owned-carts listing only applies to a logged-in
+   * customer's own carts: a company bucket and anonymous/guest carts are
+   * only known to the session, and the backend only serves the route when
+   * the cart-ownership plugin is installed.
+   */
+  async shouldUseOwnershipEndpoint(payload) {
+    if (payload.search.company) {
+      return false;
+    }
+    if (this.context.session.identityContext.identity.type !== "Registered") {
+      return false;
+    }
+    return await this.isCartOwnershipPluginEnabled();
+  }
+  /**
+   * Lists the customer's open carts through the cart-ownership plugin's
+   * `GET /store/customers/me/carts`. Returns null when the backend turns
+   * out not to serve the route after all (404: plugin configured but not
+   * built; 401: the token is no longer valid), so the caller falls back to
+   * the session-tracked list. Other errors are real backend faults and
+   * propagate.
+   */
+  async listCartsViaOwnershipEndpoint(payload) {
+    const client = await this.getClient();
+    const { pageNumber, pageSize } = payload.search.paginationOptions;
+    try {
+      const response = await client.client.fetch("/store/customers/me/carts", {
+        method: "GET",
+        query: {
+          fields: this.ownedCartListFields,
+          limit: pageSize,
+          offset: (pageNumber - 1) * pageSize,
+          order: this.ownedCartListOrder
+        }
+      });
+      return {
+        items: response.carts.map((cart) => this.normalizeOwnedCart(cart)),
+        totalCount: response.count
+      };
+    } catch (err) {
+      if (this.shouldFallBackToSessionList(err)) {
+        debug("Owned-carts endpoint unavailable, falling back to session-tracked carts:", err);
+        return null;
+      }
+      throw err;
+    }
+  }
+  /**
+   * Lists carts from the ids tracked in the session: the behavior from
+   * before the cart-ownership plugin existed, and still the only source for
+   * anonymous/guest carts and company buckets.
+   */
+  async listCartsFromSession(payload) {
     const client = await this.getClient();
     const sessionData = this.medusaApi.getSessionData();
     let cartCollection = payload.search.company ? sessionData.allOwnedCarts?.[payload.search.company.taxIdentifier] : sessionData.allOwnedCarts?.["_me"];
@@ -61,18 +144,58 @@ class MedusaCartCapability extends CartCapability {
     } else {
       cartCollection = [];
     }
-    const shortFields = ["id", "customerId", "updated_at", "metadata", "items.id"].join(",");
-    const allPromises = cartCollection.map((cartIdentifier) => client.store.cart.retrieve(cartIdentifier.key, { fields: shortFields }));
+    const allPromises = cartCollection.map((cartIdentifier) => client.store.cart.retrieve(cartIdentifier.key, { fields: this.ownedCartListFields }));
     const responses = await Promise.all(allPromises);
     const carts = responses.map((response) => response.cart).filter((cart) => !!cart);
-    return success(this.factory.parseCartPaginatedSearchResult(
-      this.context,
-      {
-        items: carts,
-        totalCount
-      },
-      payload
-    ));
+    return {
+      items: carts.map((cart) => this.normalizeOwnedCart(cart)),
+      totalCount
+    };
+  }
+  /**
+   * The factory reads `customer_id`, but only the `customer.id` relation is
+   * an allowed list field, so copy it over when `customer_id` itself wasn't
+   * returned.
+   */
+  normalizeOwnedCart(cart) {
+    return { ...cart, customer_id: cart.customer_id ?? cart.customer?.id };
+  }
+  /** A 404 (route not served) or 401 (token no longer valid) degrades to the session list. */
+  shouldFallBackToSessionList(err) {
+    return err instanceof FetchError && (err.status === 404 || err.status === 401);
+  }
+  /**
+   * Checks whether the backend has the cart-ownership plugin, by its name in
+   * core's `GET /admin/plugins`. Detection must never break cart listing, so
+   * any failure just reports the plugin as absent.
+   */
+  async isCartOwnershipPluginEnabled() {
+    const plugins = await this.fetchEnabledPlugins();
+    return plugins.includes(this.cartOwnershipPluginName);
+  }
+  /**
+   * The backend's configured plugin list, kept in the reactionary cache
+   * (shared across sessions) so not every request re-asks the admin API.
+   * Failures are not cached: a plugin-less answer from here only costs the
+   * fallback behavior, while caching a transient failure would hide the
+   * plugin for a whole TTL.
+   */
+  async fetchEnabledPlugins() {
+    const cacheKey = `medusa:plugins:${this.config.apiUrl}`;
+    const cached = await this.cache.get(cacheKey, MedusaCachedPluginListSchema);
+    if (cached) {
+      return cached.plugins;
+    }
+    try {
+      const adminClient = await new MedusaAdminAPI(this.config, this.context).getClient();
+      const response = await adminClient.client.fetch("/admin/plugins", { method: "GET" });
+      const plugins = response.plugins.map((plugin) => plugin.name);
+      await this.cache.put(cacheKey, { plugins }, { ttlSeconds: this.pluginDetectionTtlSeconds, dependencyIds: [] });
+      return plugins;
+    } catch (err) {
+      debug("Failed to list backend plugins:", err);
+      return [];
+    }
   }
   async getById(payload) {
     try {
@@ -218,6 +341,21 @@ class MedusaCartCapability extends CartCapability {
       }
     };
   }
+  /**
+   * Session tracking is skipped for a logged-in customer's own carts when
+   * the backend has the cart-ownership plugin: the backend attributes the
+   * cart to the customer at creation and lists it server-side. Anonymous
+   * carts and company buckets are still only known to the session.
+   */
+  async shouldTrackOwnedCartInSession(payload) {
+    if (payload.company) {
+      return true;
+    }
+    if (this.context.session.identityContext.identity.type !== "Registered") {
+      return true;
+    }
+    return !await this.isCartOwnershipPluginEnabled();
+  }
   addCartToOwnedList(cartIdentifier, companyId) {
     const sessionData = this.medusaApi.getSessionData();
     const companyIdToUse = companyId ? companyId.taxIdentifier : "_me";
@@ -233,6 +371,30 @@ class MedusaCartCapability extends CartCapability {
     }
     this.medusaApi.setSessionData(sessionData);
   }
+  /**
+   * Removes every trace of a cart from the session: the active cart marker
+   * (when it points at this cart) and the entry in every owned-carts
+   * collection. Used when a cart turns out to be deleted or stale upstream.
+   */
+  pruneCartFromSession(cartKey) {
+    const sessionData = this.medusaApi.getSessionData();
+    if (sessionData.activeCartId?.key === cartKey) {
+      delete sessionData.activeCartId;
+      this.medusaApi.setSessionData({ activeCartId: void 0 });
+    }
+    if (sessionData.allOwnedCarts) {
+      const prunedCollections = Object.fromEntries(
+        Object.entries(sessionData.allOwnedCarts).map(([collection, carts]) => [
+          collection,
+          carts.filter((cart) => cart.key !== cartKey)
+        ])
+      );
+      this.medusaApi.setSessionData({ allOwnedCarts: prunedCollections });
+    }
+  }
+  isNotFoundError(err) {
+    return err instanceof FetchError && err.status === 404;
+  }
   removeCartFromOwnedList(cartIdentifier, company) {
     const sessionData = this.medusaApi.getSessionData();
     const companyIdToUse = company ? company.taxIdentifier : "_me";
@@ -253,7 +415,9 @@ class MedusaCartCapability extends CartCapability {
         }
       );
       if (response.cart) {
-        this.addCartToOwnedList(this.factory.parseCartIdentifier(this.context, response.cart), payload.company);
+        if (await this.shouldTrackOwnedCartInSession(payload)) {
+          this.addCartToOwnedList(this.factory.parseCartIdentifier(this.context, response.cart), payload.company);
+        }
         this.medusaApi.setSessionData({
           activeCartId: this.factory.parseCartIdentifier(this.context, response.cart)
         });
@@ -329,18 +493,23 @@ class MedusaCartCapability extends CartCapability {
         }
       }
       if (activeCartId) {
-        const response = await client.store.cart.retrieve(activeCartId.key, { fields: "id,region_id" });
-        if (!response.cart) {
-          delete sessionData.activeCartId;
-          this.medusaApi.setSessionData({
-            activeCartId: void 0
-          });
+        let remoteCart;
+        try {
+          const response = await client.store.cart.retrieve(activeCartId.key, { fields: "id,region_id" });
+          remoteCart = response.cart;
+        } catch (retrieveError) {
+          if (!this.isNotFoundError(retrieveError)) {
+            throw retrieveError;
+          }
+        }
+        if (!remoteCart) {
+          this.pruneCartFromSession(activeCartId.key);
           return error({
             type: "NotFound",
             identifier: activeCartId
           });
         }
-        return success(this.factory.parseCartIdentifier(this.context, response.cart));
+        return success(this.factory.parseCartIdentifier(this.context, remoteCart));
       }
       return error({
         type: "NotFound",
@@ -359,13 +528,7 @@ class MedusaCartCapability extends CartCapability {
       const client = await this.getClient();
       const medusaId = payload.cart;
       if (medusaId.key) {
-        const sessionData = this.medusaApi.getSessionData();
-        if (sessionData.activeCartId) {
-          delete sessionData.activeCartId;
-          this.medusaApi.setSessionData({
-            activeCartId: void 0
-          });
-        }
+        this.pruneCartFromSession(medusaId.key);
       }
       const cartResponse = await client.store.cart.retrieve(medusaId.key);
       if (cartResponse.cart) {
@@ -374,9 +537,11 @@ class MedusaCartCapability extends CartCapability {
         }
       }
       return success(void 0);
-    } catch (error2) {
-      debug("Failed to delete cart:", error2);
-      return success(void 0);
+    } catch (err) {
+      if (this.isNotFoundError(err)) {
+        return success(void 0);
+      }
+      handleProviderError("delete cart", err);
     }
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactionary/medusa",
-  "version": "0.10.50",
+  "version": "0.10.52",
   "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.50",
+    "@reactionary/core": "0.10.52",
     "debug": "^4.4.3",
     "@medusajs/types": "^2.13.3",
     "zod": "4.1.9"

package/schema/medusa.schema.js

@@ -11,6 +11,9 @@ const MedusaRegionSchema = z.looseObject({
   name: z.string(),
   currency_code: z.string()
 });
+const MedusaCachedPluginListSchema = z.looseObject({
+  plugins: z.array(z.string())
+});
 const MedusaSessionSchema = z.looseObject({
   activeCartId: MedusaCartIdentifierSchema.optional(),
   allOwnedCarts: z.record(z.string(), z.array(MedusaCartIdentifierSchema)).optional(),
@@ -20,6 +23,7 @@ const MedusaSessionSchema = z.looseObject({
   selectedRegion: MedusaRegionSchema.optional()
 });
 export {
+  MedusaCachedPluginListSchema,
   MedusaCartIdentifierSchema,
   MedusaOrderIdentifierSchema,
   MedusaRegionSchema,

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

@@ -1,10 +1,20 @@
 import type { Cache, CartFactory, CartFactoryCartOutput, CartFactoryIdentifierOutput, CartFactoryWithOutput, CartMutationApplyCoupon, CartMutationChangeCurrency, CartMutationCreateCart, CartMutationDeleteCart, CartMutationItemAdd, CartMutationItemQuantityChange, CartMutationItemRemove, CartMutationRemoveCoupon, CartMutationRenameCart, CartPaginatedSearchResult, CartQueryById, CartQueryList, CompanyIdentifier, NotFoundError, RequestContext, Result } from '@reactionary/core';
 import { CartCapability } from '@reactionary/core';
+import type { StoreCart } from '@medusajs/types';
 import { type StoreAddCartLineItem, type StoreCartAddPromotion, type StoreCartRemovePromotion, type StoreCreateCart, type StoreUpdateCart, type StoreUpdateCartLineItem } from '@medusajs/types';
-import type { MedusaAPI } from '../core/client.js';
-import type { MedusaCartFactory } from '../factories/cart/cart.factory.js';
+import { type MedusaAPI } from '../core/client.js';
+import type { MedusaCartFactory, ParseMedusaCartPaginatedSearchResultInput } from '../factories/cart/cart.factory.js';
 import type { MedusaConfiguration } from '../schema/configuration.schema.js';
-import type { MedusaCartIdentifier } from '../schema/medusa.schema.js';
+import { type MedusaCartIdentifier } from '../schema/medusa.schema.js';
+/**
+ * A cart as returned when the `customer.id` relation field is requested;
+ * `StoreCart` itself has no `customer` property.
+ */
+interface MedusaOwnedCart extends StoreCart {
+    customer?: {
+        id: string;
+    } | null;
+}
 export declare class MedusaCartCapability<TFactory extends CartFactory = MedusaCartFactory> extends CartCapability<CartFactoryCartOutput<TFactory>, CartFactoryIdentifierOutput<TFactory>> {
     medusaApi: MedusaAPI;
     protected config: MedusaConfiguration;
@@ -16,8 +26,71 @@ export declare class MedusaCartCapability<TFactory extends CartFactory = MedusaC
      * example: this.includedFields = [includedFields, '+discounts.*'].join(',');
      */
     protected includedFields: string;
+    /**
+     * Fields requested when listing owned carts, both via the cart-ownership
+     * endpoint and via the session-tracked fallback. Every entry must be in
+     * the allowed field set of both routes; `customer.id` stands in for
+     * `customer_id`, which is not an allowed field (see normalizeOwnedCart).
+     */
+    protected ownedCartListFields: string;
+    /** Sort order for the server-side owned-carts listing. */
+    protected ownedCartListOrder: string;
+    /**
+     * Package name of the optional backend plugin that serves
+     * `GET /store/customers/me/carts` (a logged-in customer's open carts).
+     */
+    protected cartOwnershipPluginName: string;
+    /**
+     * How long a backend's plugin list stays cached. Bounds how late a newly
+     * (un)installed cart-ownership plugin is noticed.
+     */
+    protected pluginDetectionTtlSeconds: number;
     constructor(config: MedusaConfiguration, cache: Cache, context: RequestContext, medusaApi: MedusaAPI, factory: CartFactoryWithOutput<TFactory>);
     listCarts(payload: CartQueryList): Promise<Result<CartPaginatedSearchResult>>;
+    /**
+     * The server-side owned-carts listing only applies to a logged-in
+     * customer's own carts: a company bucket and anonymous/guest carts are
+     * only known to the session, and the backend only serves the route when
+     * the cart-ownership plugin is installed.
+     */
+    protected shouldUseOwnershipEndpoint(payload: CartQueryList): Promise<boolean>;
+    /**
+     * Lists the customer's open carts through the cart-ownership plugin's
+     * `GET /store/customers/me/carts`. Returns null when the backend turns
+     * out not to serve the route after all (404: plugin configured but not
+     * built; 401: the token is no longer valid), so the caller falls back to
+     * the session-tracked list. Other errors are real backend faults and
+     * propagate.
+     */
+    protected listCartsViaOwnershipEndpoint(payload: CartQueryList): Promise<ParseMedusaCartPaginatedSearchResultInput | null>;
+    /**
+     * Lists carts from the ids tracked in the session: the behavior from
+     * before the cart-ownership plugin existed, and still the only source for
+     * anonymous/guest carts and company buckets.
+     */
+    protected listCartsFromSession(payload: CartQueryList): Promise<ParseMedusaCartPaginatedSearchResultInput>;
+    /**
+     * The factory reads `customer_id`, but only the `customer.id` relation is
+     * an allowed list field, so copy it over when `customer_id` itself wasn't
+     * returned.
+     */
+    protected normalizeOwnedCart(cart: MedusaOwnedCart): StoreCart;
+    /** A 404 (route not served) or 401 (token no longer valid) degrades to the session list. */
+    protected shouldFallBackToSessionList(err: unknown): boolean;
+    /**
+     * Checks whether the backend has the cart-ownership plugin, by its name in
+     * core's `GET /admin/plugins`. Detection must never break cart listing, so
+     * any failure just reports the plugin as absent.
+     */
+    protected isCartOwnershipPluginEnabled(): Promise<boolean>;
+    /**
+     * The backend's configured plugin list, kept in the reactionary cache
+     * (shared across sessions) so not every request re-asks the admin API.
+     * Failures are not cached: a plugin-less answer from here only costs the
+     * fallback behavior, while caching a transient failure would hide the
+     * plugin for a whole TTL.
+     */
+    protected fetchEnabledPlugins(): Promise<string[]>;
     getById(payload: CartQueryById): Promise<Result<CartFactoryCartOutput<TFactory>, NotFoundError>>;
     /**
      * Extension point for the `add` operation to control the payload sent to Medusa when adding an item to the cart. By default, it only includes the variant ID and quantity, but you can override it to include more fields as needed.
@@ -35,7 +108,21 @@ export declare class MedusaCartCapability<TFactory extends CartFactory = MedusaC
      * @returns
      */
     protected createCartPayload(payload: CartMutationCreateCart): Promise<StoreCreateCart>;
+    /**
+     * Session tracking is skipped for a logged-in customer's own carts when
+     * the backend has the cart-ownership plugin: the backend attributes the
+     * cart to the customer at creation and lists it server-side. Anonymous
+     * carts and company buckets are still only known to the session.
+     */
+    protected shouldTrackOwnedCartInSession(payload: CartMutationCreateCart): Promise<boolean>;
     protected addCartToOwnedList(cartIdentifier: MedusaCartIdentifier, companyId?: CompanyIdentifier): void;
+    /**
+     * Removes every trace of a cart from the session: the active cart marker
+     * (when it points at this cart) and the entry in every owned-carts
+     * collection. Used when a cart turns out to be deleted or stale upstream.
+     */
+    protected pruneCartFromSession(cartKey: string): void;
+    protected isNotFoundError(err: unknown): boolean;
     protected removeCartFromOwnedList(cartIdentifier: MedusaCartIdentifier, company?: CompanyIdentifier): void;
     createCart(payload: CartMutationCreateCart): Promise<Result<CartFactoryCartOutput<TFactory>>>;
     remove(payload: CartMutationItemRemove): Promise<Result<CartFactoryCartOutput<TFactory>>>;
@@ -77,3 +164,4 @@ export declare class MedusaCartCapability<TFactory extends CartFactory = MedusaC
         auth: import("@medusajs/js-sdk").Auth;
     }>;
 }
+export {};

package/src/schema/medusa.schema.d.ts

@@ -13,6 +13,13 @@ export declare const MedusaRegionSchema: z.ZodObject<{
     name: z.ZodString;
     currency_code: z.ZodString;
 }, z.core.$loose>;
+/**
+ * Cache entry shape for a backend's configured plugin list, as reported by
+ * core's `GET /admin/plugins`.
+ */
+export declare const MedusaCachedPluginListSchema: z.ZodObject<{
+    plugins: z.ZodArray<z.ZodString>;
+}, z.core.$loose>;
 export declare const MedusaSessionSchema: z.ZodObject<{
     activeCartId: z.ZodOptional<z.ZodObject<{
         key: z.ZodString;
@@ -37,5 +44,6 @@ export declare const MedusaSessionSchema: z.ZodObject<{
 }, z.core.$loose>;
 export type MedusaCartIdentifier = InferType<typeof MedusaCartIdentifierSchema>;
 export type MedusaOrderIdentifier = z.infer<typeof MedusaOrderIdentifierSchema>;
+export type MedusaCachedPluginList = z.infer<typeof MedusaCachedPluginListSchema>;
 export type MedusaSession = z.infer<typeof MedusaSessionSchema>;
 export type MedusaRegion = z.infer<typeof MedusaRegionSchema>;