Athos Commerce

@weareseeed/medusa-athos-plugin

Medusa v2 plugin that generates a streaming NDJSON product feed for Athos Commerce integration.

Features

• Streaming NDJSON product feed (one line per variant + one product summary line)
• Token-based feed authentication
• Price filtering by region
• Product filtering by sales channel
• Configurable swatch options
• Extensible via Copy to clipboardextraProductFields and Copy to clipboardtransformLine hooks
• Admin API to manage plugin configuration

Requirements

• Medusa v2
• Node.js >= 20

Installation

1
yarn add @weareseeed/medusa-athos-plugin

Setup

1. Register the plugin

1234567891011
// medusa-config.ts
import { defineConfig } from "@medusajs/framework/config"

export default defineConfig({
  plugins: [
    {
      resolve: "@weareseeed/medusa-athos-plugin",
      options: {},
    },
  ],
})

2. Run migrations

1
npx medusa db:migrate

3. Configure via Admin API

Set the plugin configuration through the authenticated admin endpoint:

12345678910
curl -X POST http://localhost:9000/admin/athos/config \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "storefront_url": "https://mystore.com",
    "feed_token": "a-secret-token",
    "region_id": "reg_01...",
    "sales_channel_ids": ["sc_01..."],
    "swatch_option_titles": ["color", "colour"]
  }'

Field Type Required Description Copy to clipboardstorefront_url Copy to clipboardstring Yes Base URL prepended to Copy to clipboard/products/<handle> for each product URL Copy to clipboardfeed_token Copy to clipboardstring Yes Secret token required to access the feed endpoint Copy to clipboardregion_id Copy to clipboardstring No When set, prices are filtered to the region's currency Copy to clipboardsales_channel_ids Copy to clipboardstring[] No When set, only products in these sales channels are included Copy to clipboardswatch_option_titles Copy to clipboardstring[] No Option titles treated as swatches (default: Copy to clipboard["color", "colour"])

Feed Endpoint

1
GET /athos/feed?token=<feed_token>

Returns an Copy to clipboardapplication/x-ndjson stream. Each product produces:

1. One variant line per variant
2. One product summary line

Variant line fields

Field Description Copy to clipboardProduct ID Variant ID Copy to clipboardSKU Variant SKU Copy to clipboardName Variant title Copy to clipboardProduct URL Copy to clipboard<storefront_url>/products/<handle> Copy to clipboardPrice Lowest price for the variant (filtered by region if configured) Copy to clipboardRetail Price Copy to clipboardcompare_at_price Copy to clipboardThumbnail URL Product thumbnail Copy to clipboardDescription Product description Copy to clipboardCategory Array of category path strings (e.g. Copy to clipboard"Parent>Child") Copy to clipboardCategory ID Array of category IDs Copy to clipboardSearch Keywords Comma-separated product tags Copy to clipboard__parent_id Parent product ID Copy to clipboard__parent_title Parent product title Copy to clipboard__parent_image Parent product thumbnail Copy to clipboard__variant_position 1-based position within the product Copy to clipboard__in_stock Copy to clipboardtrue if the variant is available Copy to clipboard__in_stock_pct % of variants in stock across the product Copy to clipboard__standard_options All product options with positions and values Copy to clipboard__selected_options This variant's chosen option values Copy to clipboard__swatch_options Values of configured swatch options (product-level)

Product summary line fields

Same as variant line minus all Copy to clipboard__ private fields, with Copy to clipboardProduct ID set to the product ID and Copy to clipboardPrice set to the lowest price across all variants.

Example

12
{"Product ID":"variant_01...","SKU":"1","Name":"blue, m","Product URL":"https://mystore.com/products/example","Price":10,"Thumbnail URL":"https://...","Description":"...","Category":["Tops"],"Category ID":["pcat_01..."],"__parent_id":"prod_01...","__parent_title":"Example Product","__parent_image":"https://...","__variant_position":1,"__in_stock":true,"__in_stock_pct":100,"__standard_options":{"color":{"position":0,"values":["red","blue"]},"size":{"position":1,"values":["s","m"]}},"__selected_options":{"color":{"value":"blue"},"size":{"value":"m"}},"__swatch_options":{"red":{"value":"red"},"blue":{"value":"blue"}}}
{"Product ID":"prod_01...","Name":"Example Product","Product URL":"https://mystore.com/products/example","Price":10,"Thumbnail URL":"https://...","Description":"...","Category":["Tops"],"Category ID":["pcat_01..."]}

Plugin Options

Pass options when registering the plugin in Copy to clipboardmedusa-config.ts to extend the feed.

1234567891011121314151617181920
import { defineConfig } from "@medusajs/framework/config"
import type { FeedLineContext } from "@weareseeed/medusa-athos-plugin/types"

export default defineConfig({
  plugins: [
    {
      resolve: "@weareseeed/medusa-athos-plugin",
      options: {
        feed: {
          extraProductFields: ["metadata", "variants.metadata"],
          transformLine: (line, ctx: FeedLineContext) => {
            line["Brand"] = (ctx.product as any).metadata?.brand ?? undefined

            if (ctx.type === "variant") {
              line["Custom Variant Field"] = (ctx.variant as any).metadata?.custom ?? undefined
            }

            if (ctx.type === "product") {
              line["Custom Product Field"] = (ctx.product as any).metadata?.custom ?? undefined
            }

Copy to clipboardfeed.extraProductFields

Copy to clipboardstring[] — Additional Medusa product fields to fetch and make available inside Copy to clipboardtransformLine. Uses the same dot-notation field paths as Medusa's Copy to clipboardquery.graph.

123456
extraProductFields: [
  "metadata",
  "variants.metadata",
  "images.url",
  "collection.title",
]

Copy to clipboardfeed.transformLine

12
(line: Record<string, unknown>, ctx: FeedLineContext) =>
  Record<string, unknown> | Promise<Record<string, unknown>>

Called for every line written to the feed. Use it to add, remove, or transform fields. The Copy to clipboardctx argument provides typed access to the raw product and variant data:

123
type FeedLineContext =
  | { type: "variant"; product: Record<string, unknown>; variant: Record<string, unknown>; variantIndex: number }
  | { type: "product"; product: Record<string, unknown> }

Fields that resolve to Copy to clipboardundefined are automatically stripped from the output.

Admin API

Both endpoints require an authenticated admin JWT.

Method Path Description Copy to clipboardGET Copy to clipboard/admin/athos/config Retrieve the current configuration Copy to clipboardPOST Copy to clipboard/admin/athos/config Create or update the configuration

License

MIT — Seeed