medusa-product-feed 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+# medusa-product-feed
+
+A self-contained Medusa v2 plugin that generates a Google Merchant Center–compatible XML product feed at `GET /store/feed`. Ships its own API route and cache-invalidation subscriber — the consuming project needs zero extra files.
+
+## What it does
+
+- Generates a Google Shopping RSS XML feed from your Medusa product catalog
+- Caches the feed in Redis and auto-invalidates on `product.created`, `product.updated`, and `product.deleted` events
+- Supports three variant rendering modes: `parent`, `children`, and `config` (runtime query param)
+- Reads all configuration from environment variables
+
+## Installation
+
+```bash
+npm install medusa-product-feed
+# or with pnpm
+pnpm add medusa-product-feed
+```
+
+For local development with a symlinked package:
+
+```bash
+cd /path/to/shared-medusa-utils/medusa-product-feed && npm run build
+cd /path/to/your-medusa-backend && pnpm link /path/to/shared-medusa-utils/medusa-product-feed
+```
+
+## Configuration
+
+Set environment variables in your `.env`:
+
+| Variable              | Default                    | Description                                                    |
+|-----------------------|----------------------------|----------------------------------------------------------------|
+| `FEED_STOREFRONT_URL` | `$STOREFRONT_URL` or `http://localhost:8000` | Base URL for product links in the feed      |
+| `FEED_CURRENCY`       | `ILS`                      | Currency code for prices                                       |
+| `FEED_REGION_ID`      | _(empty)_                  | Medusa region ID to use for pricing                            |
+| `FEED_VARIANT_MODE`   | `children`                 | Variant rendering mode: `parent`, `children`, or `config`      |
+| `FEED_CACHE_TTL`      | `3600`                     | Cache TTL in seconds                                           |
+| `FEED_DISABLE_CACHE`  | `false`                    | Set to `true` to disable Redis caching (useful in development) |
+| `FEED_STORE_NAME`     | _(none)_                   | Store name included in the feed `<title>`                      |
+
+## Usage
+
+Register the plugin in your `medusa-config.js` (or `medusa-config.ts`):
+
+```js
+module.exports = defineConfig({
+  plugins: [
+    {
+      resolve: "medusa-product-feed",
+      options: {},
+    },
+  ],
+  // ...
+})
+```
+
+That's it. No extra files needed in your project. The plugin automatically registers:
+
+- `GET /store/feed` — the XML product feed endpoint
+- A subscriber that invalidates the feed cache on product changes
+
+## Feed URL
+
+```
+GET /store/feed
+```
+
+Returns `application/xml` with a Google Merchant Center–compatible RSS feed.
+
+Response headers:
+- `X-Feed-Cache: HIT` — served from Redis cache
+- `X-Feed-Cache: MISS` — freshly generated and cached
+- `X-Feed-Cache: DISABLED` — caching is disabled
+
+## Variant modes
+
+| Mode       | Behavior                                                                 |
+|------------|--------------------------------------------------------------------------|
+| `parent`   | One feed item per product (uses the first variant for price/SKU)         |
+| `children` | One feed item per variant (each variant is a separate `<item>`)          |
+| `config`   | Resolved at request time via `?variants=parent` or `?variants=children`  |
+
+When `FEED_VARIANT_MODE=config`, callers control the mode per request:
+
+```
+GET /store/feed?variants=children
+GET /store/feed?variants=parent
+```
+
+## Cache behavior
+
+The feed is cached in Redis using the Medusa cache module. Cache keys:
+
+- `product-feed` — used for `parent` and `children` modes
+- `product-feed:parent` / `product-feed:children` — used when mode is `config`
+
+All keys are invalidated automatically when any product is created, updated, or deleted.
+
+To disable caching (e.g. in development):
+
+```env
+FEED_DISABLE_CACHE=true
+```
+
+## Advanced: custom config per request
+
+If you need custom configuration beyond what env vars provide (e.g. multi-tenant logic), you can use the `createFeedRouteHandler` factory directly in your own route file:
+
+```ts
+// src/api/store/feed/route.ts
+import { createFeedRouteHandler } from "medusa-product-feed"
+
+export const GET = createFeedRouteHandler({
+  storefrontUrl: "https://mystore.com",
+  currency: "USD",
+  regionId: "reg_01ABC",
+  variantMode: "children",
+  cacheTtlSeconds: 1800,
+  disableCache: false,
+  storeName: "My Store",
+})
+```

package/dist/api/store/feed/route.d.ts

@@ -0,0 +1 @@
+export declare const GET: (req: import("@medusajs/framework").MedusaRequest, res: import("@medusajs/framework").MedusaResponse) => Promise<void>;

package/dist/api/store/feed/route.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = void 0;
+const route_1 = require("../../../route");
+const types_1 = require("../../../types");
+exports.GET = (0, route_1.createFeedRouteHandler)((0, types_1.feedConfigFromEnv)());

package/dist/feed-builder.d.ts

@@ -0,0 +1,2 @@
+import type { FeedConfig, FeedProduct } from "./types";
+export declare function buildGoogleMerchantFeed(products: FeedProduct[], config: FeedConfig): string;

package/dist/feed-builder.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGoogleMerchantFeed = buildGoogleMerchantFeed;
+function escapeXml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function stripHtml(html) {
+    return html.replace(/<[^>]*>/g, "").trim();
+}
+function formatPrice(amount, currency) {
+    return `${(amount / 100).toFixed(2)} ${currency.toUpperCase()}`;
+}
+function getPrice(variant, currency) {
+    const price = variant.prices.find((p) => p.currency_code.toLowerCase() === currency.toLowerCase());
+    return price ? formatPrice(price.amount, currency) : null;
+}
+function getAvailability(variant) {
+    if (!variant.manage_inventory)
+        return "in stock";
+    return variant.inventory_quantity > 0 ? "in stock" : "out of stock";
+}
+function getBrand(product, storeName) {
+    if (product.metadata?.brand)
+        return String(product.metadata.brand);
+    if (product.collection?.title)
+        return product.collection.title;
+    return storeName;
+}
+function buildItem(id, itemGroupId, product, variant, config) {
+    const title = itemGroupId
+        ? `${product.title}${variant.title ? ` - ${variant.title}` : ""}`
+        : product.title;
+    const description = product.description ? stripHtml(product.description) : "";
+    const brand = getBrand(product, config.storeName ?? "");
+    const price = getPrice(variant, config.currency);
+    const availability = getAvailability(variant);
+    const link = `${config.storefrontUrl}/products/${product.handle}`;
+    const imageLink = product.images[0]?.url ?? "";
+    const additionalImages = product.images
+        .slice(1, 10)
+        .map((img) => `    <g:additional_image_link>${escapeXml(img.url)}</g:additional_image_link>`)
+        .join("\n");
+    const category = product.metadata?.google_category
+        ? `    <g:google_product_category>${escapeXml(String(product.metadata.google_category))}</g:google_product_category>`
+        : "";
+    return [
+        "  <item>",
+        `    <g:id>${escapeXml(id)}</g:id>`,
+        itemGroupId ? `    <g:item_group_id>${escapeXml(itemGroupId)}</g:item_group_id>` : null,
+        `    <title>${escapeXml(title)}</title>`,
+        `    <description>${escapeXml(description)}</description>`,
+        `    <link>${escapeXml(link)}</link>`,
+        imageLink ? `    <g:image_link>${escapeXml(imageLink)}</g:image_link>` : null,
+        additionalImages || null,
+        price ? `    <g:price>${escapeXml(price)}</g:price>` : null,
+        `    <g:availability>${availability}</g:availability>`,
+        `    <g:condition>${escapeXml(String(product.metadata?.condition ?? "new"))}</g:condition>`,
+        `    <g:brand>${escapeXml(brand)}</g:brand>`,
+        category || null,
+        "  </item>",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function buildGoogleMerchantFeed(products, config) {
+    if (config.variantMode === "config") {
+        throw new Error('buildGoogleMerchantFeed: variantMode "config" must be resolved to "parent" or "children" before calling this function');
+    }
+    const items = [];
+    for (const product of products) {
+        if (config.variantMode === "parent") {
+            const firstVariant = product.variants[0];
+            if (!firstVariant)
+                continue;
+            items.push(buildItem(product.id, null, product, firstVariant, config));
+        }
+        else {
+            for (const variant of product.variants) {
+                items.push(buildItem(variant.id, product.id, product, variant, config));
+            }
+        }
+    }
+    const storeTitle = escapeXml(config.storeName ?? "Product Feed");
+    const storeUrl = escapeXml(config.storefrontUrl);
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0">',
+        "<channel>",
+        `  <title>${storeTitle}</title>`,
+        `  <link>${storeUrl}</link>`,
+        `  <description>${storeTitle} product feed for Google Merchant Center</description>`,
+        ...items,
+        "</channel>",
+        "</rss>",
+    ].join("\n");
+}

package/dist/feed-cache.d.ts

@@ -0,0 +1,9 @@
+interface CacheService {
+    get<T>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttl?: number): Promise<void>;
+    invalidate(key: string): Promise<void>;
+}
+export declare function getFeed(cache: CacheService, key?: string): Promise<string | null>;
+export declare function setFeed(cache: CacheService, xml: string, ttlSeconds: number, key?: string): Promise<void>;
+export declare function invalidateFeed(cache: CacheService, key?: string): Promise<void>;
+export {};

package/dist/feed-cache.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFeed = getFeed;
+exports.setFeed = setFeed;
+exports.invalidateFeed = invalidateFeed;
+const DEFAULT_CACHE_KEY = "product-feed";
+async function getFeed(cache, key = DEFAULT_CACHE_KEY) {
+    return cache.get(key);
+}
+async function setFeed(cache, xml, ttlSeconds, key = DEFAULT_CACHE_KEY) {
+    await cache.set(key, xml, ttlSeconds);
+}
+async function invalidateFeed(cache, key = DEFAULT_CACHE_KEY) {
+    await cache.invalidate(key);
+}

package/dist/feed-query.d.ts

@@ -0,0 +1,8 @@
+import type { FeedProduct } from "./types";
+interface RemoteQuery {
+    graph(options: object): Promise<{
+        data: any[];
+    }>;
+}
+export declare function fetchFeedProducts(query: RemoteQuery, currency: string, regionId: string): Promise<FeedProduct[]>;
+export {};

package/dist/feed-query.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchFeedProducts = fetchFeedProducts;
+const utils_1 = require("@medusajs/framework/utils");
+async function fetchFeedProducts(query, currency, regionId) {
+    if (!regionId) {
+        console.warn("[medusa-product-feed] FEED_REGION_ID is not set — prices may not resolve correctly");
+    }
+    const pricingContext = { currency_code: currency.toLowerCase() };
+    if (regionId)
+        pricingContext.region_id = regionId;
+    const { data: products } = await query.graph({
+        entity: "product",
+        fields: [
+            "id",
+            "title",
+            "handle",
+            "description",
+            "status",
+            "metadata",
+            "images.url",
+            "collection.title",
+            "variants.id",
+            "variants.title",
+            "variants.sku",
+            "variants.manage_inventory",
+            "variants.inventory_quantity",
+            "variants.calculated_price.calculated_amount",
+            "variants.calculated_price.currency_code",
+        ],
+        filters: { status: "published" },
+        context: {
+            variants: {
+                calculated_price: (0, utils_1.QueryContext)(pricingContext),
+            },
+        },
+    });
+    return products.map((p) => ({
+        id: p.id,
+        title: p.title ?? "",
+        handle: p.handle ?? "",
+        description: p.description ?? null,
+        images: (p.images ?? []).map((img) => ({ url: img.url })),
+        collection: p.collection ? { title: p.collection.title } : null,
+        variants: (p.variants ?? []).map((v) => ({
+            id: v.id,
+            title: v.title ?? null,
+            sku: v.sku ?? null,
+            // calculated_amount is in display units (e.g. 99.00), multiply by 100 to match FeedVariant.prices minor-unit convention
+            prices: v.calculated_price?.calculated_amount != null
+                ? [{ currency_code: currency.toLowerCase(), amount: Math.round(v.calculated_price.calculated_amount * 100) }]
+                : [],
+            manage_inventory: v.manage_inventory ?? false,
+            inventory_quantity: v.inventory_quantity ?? 0,
+        })),
+        metadata: p.metadata ?? null,
+    }));
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { FeedConfig, FeedProduct, FeedVariant, VariantMode } from "./types";
+export { feedConfigFromEnv } from "./types";
+export { buildGoogleMerchantFeed } from "./feed-builder";
+export { getFeed, setFeed, invalidateFeed } from "./feed-cache";
+export { fetchFeedProducts } from "./feed-query";
+export { createFeedRouteHandler } from "./route";
+export { default as productFeedInvalidationSubscriber, config as subscriberConfig } from "./subscribers/product-feed-invalidation";

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subscriberConfig = exports.productFeedInvalidationSubscriber = exports.createFeedRouteHandler = exports.fetchFeedProducts = exports.invalidateFeed = exports.setFeed = exports.getFeed = exports.buildGoogleMerchantFeed = exports.feedConfigFromEnv = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "feedConfigFromEnv", { enumerable: true, get: function () { return types_1.feedConfigFromEnv; } });
+var feed_builder_1 = require("./feed-builder");
+Object.defineProperty(exports, "buildGoogleMerchantFeed", { enumerable: true, get: function () { return feed_builder_1.buildGoogleMerchantFeed; } });
+var feed_cache_1 = require("./feed-cache");
+Object.defineProperty(exports, "getFeed", { enumerable: true, get: function () { return feed_cache_1.getFeed; } });
+Object.defineProperty(exports, "setFeed", { enumerable: true, get: function () { return feed_cache_1.setFeed; } });
+Object.defineProperty(exports, "invalidateFeed", { enumerable: true, get: function () { return feed_cache_1.invalidateFeed; } });
+var feed_query_1 = require("./feed-query");
+Object.defineProperty(exports, "fetchFeedProducts", { enumerable: true, get: function () { return feed_query_1.fetchFeedProducts; } });
+var route_1 = require("./route");
+Object.defineProperty(exports, "createFeedRouteHandler", { enumerable: true, get: function () { return route_1.createFeedRouteHandler; } });
+var product_feed_invalidation_1 = require("./subscribers/product-feed-invalidation");
+Object.defineProperty(exports, "productFeedInvalidationSubscriber", { enumerable: true, get: function () { return __importDefault(product_feed_invalidation_1).default; } });
+Object.defineProperty(exports, "subscriberConfig", { enumerable: true, get: function () { return product_feed_invalidation_1.config; } });

package/dist/route.d.ts

@@ -0,0 +1,3 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework";
+import type { FeedConfig } from "./types";
+export declare function createFeedRouteHandler(config: FeedConfig): (req: MedusaRequest, res: MedusaResponse) => Promise<void>;

package/dist/route.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFeedRouteHandler = createFeedRouteHandler;
+const utils_1 = require("@medusajs/framework/utils");
+const feed_cache_1 = require("./feed-cache");
+const feed_query_1 = require("./feed-query");
+const feed_builder_1 = require("./feed-builder");
+function createFeedRouteHandler(config) {
+    return async function GET(req, res) {
+        try {
+            const cacheService = req.scope.resolve(utils_1.Modules.CACHE);
+            const query = req.scope.resolve(utils_1.ContainerRegistrationKeys.QUERY);
+            let resolvedVariantMode = config.variantMode;
+            if (config.variantMode === "config") {
+                const qv = req.query["variants"];
+                if (typeof qv === "string" && (qv === "parent" || qv === "children")) {
+                    resolvedVariantMode = qv;
+                }
+                else {
+                    resolvedVariantMode = "children";
+                }
+            }
+            const cacheKey = `product-feed:${resolvedVariantMode}`;
+            const effectiveConfig = { ...config, variantMode: resolvedVariantMode };
+            if (!config.disableCache) {
+                const cached = await (0, feed_cache_1.getFeed)(cacheService, cacheKey);
+                if (cached) {
+                    res.setHeader("Content-Type", "application/xml; charset=utf-8");
+                    res.setHeader("X-Feed-Cache", "HIT");
+                    res.send(cached);
+                    return;
+                }
+            }
+            const products = await (0, feed_query_1.fetchFeedProducts)(query, config.currency, config.regionId);
+            const xml = (0, feed_builder_1.buildGoogleMerchantFeed)(products, effectiveConfig);
+            if (!config.disableCache) {
+                await (0, feed_cache_1.setFeed)(cacheService, xml, config.cacheTtlSeconds, cacheKey);
+            }
+            res.setHeader("Content-Type", "application/xml; charset=utf-8");
+            res.setHeader("X-Feed-Cache", config.disableCache ? "DISABLED" : "MISS");
+            res.send(xml);
+        }
+        catch (err) {
+            console.error("[medusa-product-feed] error:", err);
+            res.status(500).send("Feed generation failed");
+        }
+    };
+}

package/dist/subscriber.d.ts

@@ -0,0 +1,3 @@
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/medusa";
+export declare function productFeedInvalidationSubscriber({ container, }: SubscriberArgs<unknown>): Promise<void>;
+export declare const config: SubscriberConfig;

package/dist/subscriber.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.productFeedInvalidationSubscriber = productFeedInvalidationSubscriber;
+const utils_1 = require("@medusajs/framework/utils");
+const feed_cache_1 = require("./feed-cache");
+async function productFeedInvalidationSubscriber({ container, }) {
+    const cacheService = container.resolve(utils_1.Modules.CACHE);
+    // Invalidate all possible cache keys (fixed key + per-mode keys)
+    await Promise.all([
+        (0, feed_cache_1.invalidateFeed)(cacheService),
+        (0, feed_cache_1.invalidateFeed)(cacheService, "product-feed:parent"),
+        (0, feed_cache_1.invalidateFeed)(cacheService, "product-feed:children"),
+    ]);
+}
+exports.config = {
+    event: [
+        "product.created",
+        "product.updated",
+        "product.deleted",
+    ],
+};

package/dist/subscribers/product-feed-invalidation.d.ts

@@ -0,0 +1,3 @@
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/medusa";
+export default function productFeedInvalidationSubscriber({ container, }: SubscriberArgs<unknown>): Promise<void>;
+export declare const config: SubscriberConfig;

package/dist/subscribers/product-feed-invalidation.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.default = productFeedInvalidationSubscriber;
+const utils_1 = require("@medusajs/framework/utils");
+const feed_cache_1 = require("../feed-cache");
+async function productFeedInvalidationSubscriber({ container, }) {
+    const cacheService = container.resolve(utils_1.Modules.CACHE);
+    await Promise.all([
+        (0, feed_cache_1.invalidateFeed)(cacheService, "product-feed:parent"),
+        (0, feed_cache_1.invalidateFeed)(cacheService, "product-feed:children"),
+    ]);
+}
+exports.config = {
+    event: ["product.created", "product.updated", "product.deleted"],
+};

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+export type VariantMode = "parent" | "children" | "config";
+export interface FeedConfig {
+    storefrontUrl: string;
+    currency: string;
+    regionId: string;
+    variantMode: VariantMode;
+    cacheTtlSeconds: number;
+    disableCache?: boolean;
+    storeName?: string;
+}
+export interface FeedVariant {
+    id: string;
+    title: string | null;
+    sku: string | null;
+    prices: Array<{
+        currency_code: string;
+        amount: number;
+    }>;
+    manage_inventory: boolean;
+    inventory_quantity: number;
+}
+export interface FeedProduct {
+    id: string;
+    title: string;
+    handle: string;
+    description: string | null;
+    images: Array<{
+        url: string;
+    }>;
+    collection: {
+        title: string;
+    } | null;
+    variants: FeedVariant[];
+    metadata: Record<string, unknown> | null;
+}
+export declare function feedConfigFromEnv(): FeedConfig;

package/dist/types.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.feedConfigFromEnv = feedConfigFromEnv;
+function feedConfigFromEnv() {
+    return {
+        storefrontUrl: process.env.FEED_STOREFRONT_URL ?? process.env.STOREFRONT_URL ?? "http://localhost:8000",
+        currency: process.env.FEED_CURRENCY ?? "ILS",
+        regionId: process.env.FEED_REGION_ID ?? "",
+        variantMode: (process.env.FEED_VARIANT_MODE ?? "children"),
+        cacheTtlSeconds: Number(process.env.FEED_CACHE_TTL ?? 3600),
+        disableCache: process.env.FEED_DISABLE_CACHE === "true",
+        storeName: process.env.FEED_STORE_NAME,
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "medusa-product-feed",
+  "version": "0.1.0",
+  "description": "Google Merchant Center XML product feed plugin for Medusa 2.x",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:unit": "jest src"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.5.7",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.25",
+    "jest": "^29.7.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@medusajs/framework": "^2.13.6",
+    "@medusajs/medusa": "^2.13.6"
+  }
+}