[Feature] Medusa.js Integration for Product Catalog

[michnowak]

Is your feature request related to a problem? Please describe.

Users need the ability to browse and display product catalogs from Medusa.js e-commerce platform in their O2S self-service applications. Currently, there is no native integration to fetch, display, and manage products from Medusa, making it difficult for applications that rely on Medusa as their primary commerce platform.

Describe the solution you'd like

A complete integration with Medusa.js commerce platform that implements the framework's Products.Service interface and provides comprehensive product catalog capabilities.

Core Functionality

Product List Management

• Product listing with pagination support (limit/offset)
• Category filtering - filter products by category
• Published products only - automatically filters for published status
• Multi-currency support - displays prices in configured default currency
• Comprehensive data - includes variants, prices, options, categories, tags, and images

Product Detail View

• Flexible identification - retrieve by product ID or SEO-friendly handle
• Variant management - full support for product variants with individual pricing
• Product options - configurable options (Size, Color, Material, etc.) with unique values
• Rich metadata - extract keySpecs and detailedSpecs from product/variant metadata
• Physical specifications - weight, dimensions (height, width, length)
• Material properties - material type, origin country, HS code, MID code

Product Recommendations

• Related products - display products related to current item
• Reference types - support for cross-sell, up-sell, and accessories
• Enhanced discovery - improve customer experience with relevant suggestions

Data Normalization

Product List Fields

• id, title, subtitle, description from Medusa product
• handle for SEO-friendly URLs
• sku, variantId from first variant
• price from variant prices matching default currency
• category from first product category
• images and thumbnail from product images
• link generated as /products/{handle} or /products/{id}
• tags from product tags

Product Detail Fields

• All list fields plus:
• keySpecs - parsed from metadata (format: [{ value, icon }])
• detailedSpecs - mapped from variant attributes:
  • Weight
  • Dimensions (Height, Width, Length)
  • Material
  • Origin Country
  • HS Code / MID Code
• variants - list of available variants with:
  • Variant ID and title
  • SKU-based slug
  • Options map (e.g., { "opt_color": "Red", "opt_size": "M" })
• options - grouped option configurations (Size: [S, M, L], Color: [Red, Blue])

Variant Selection

• Smart variant routing - generate URLs like /products/{handle}/{variant-sku}
• Default variant - use first variant if none specified
• Option groups - extract and organize variant options by type
• Slugified SKUs - convert SKUs to URL-friendly slugs

Technical Implementation

Medusa SDK Integration

• Uses official @medusajs/js-sdk for API communication
• Admin API for extended product data access
• Field selection optimization for performance
• Automatic error handling with graceful fallbacks

Field Expansion Strategy

// Product List
fields: '*variants,*variants.prices,*variants.options,*categories,*tags,*images'

// Product Detail  
fields: '+weight,+height,+width,+length,+material,+origin_country,+hs_code,+mid_code,+metadata,+product.metadata,+product.handle,product.*,*product.images,*product.tags,*options,*options.option'

Slug Generation

• Product links: /products/{handle} (SEO-friendly) or /products/{id} (fallback)
• Variant links: /products/{handle}/{variant-sku-slug}
• Slugification: Convert SKUs to lowercase, remove diacritics, replace non-alphanumeric with dashes

Metadata Parsing

• keySpecs: Stored as JSON string in metadata, parsed to array
  • Variant metadata takes precedence over product metadata
  • Expected format: [{ "value": "1200W", "icon": "Zap" }, ...]
• detailedSpecs: Dynamically extracted from variant fields
  • Variant attributes override product attributes
  • Automatic label formatting (snake_case → Title Case)

Installation & Configuration

1. Install package: npm install @o2s/integrations.medusajs --workspace=@o2s/configs.integrations
2. Configure in packages/configs/integrations/src/models/products.ts
3. Set environment variables:
   • MEDUSAJS_BASE_URL - Medusa server URL
   • MEDUSAJS_PUBLISHABLE_API_KEY - Storefront API key
   • MEDUSAJS_ADMIN_API_KEY - Admin API key
   • DEFAULT_CURRENCY - Default currency code (EUR, USD, PLN)

Supported Methods

All methods from Products.Service interface:

• ✅ getProductList(query) - List products with filters and pagination
• ✅ getProduct(params) - Retrieve single product with variants

Features Not Implemented

• Purchase/checkout flows (read-only integration for self-service)
• Inventory management
• Product creation/editing (managed in Medusa Admin)

Additional context (if applicable)

• Documentation: /apps/docs/docs/integrations/commerce/medusa-js/
• Implementation: /packages/integrations/medusajs/src/modules/products/
• Follows same architectural patterns as other O2S integrations (Zendesk, etc.)
• Compatible with Medusa v2 Admin API
• Includes comprehensive unit tests (mapper and service)
• Supports both Medusa Cloud and self-hosted instances

---

This repo is using Opire - what does it mean? 👇

💵 Everyone can add rewards for this issue commenting /reward 100 (replace 100 with the amount).
🕵️‍♂️ If someone starts working on this issue to earn the rewards, they can comment /try to let everyone know!
🙌 And when they open the PR, they can comment /claim #670 either in the PR description or in a PR's comment.

🪙 Also, everyone can tip any user commenting /tip 20 @michnowak (replace 20 with the amount, and @michnowak with the user to tip).

📖 If you want to learn more, check out our documentation.