Athos plugin

@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 extraProductFields and transformLine hooks
• Admin API to manage plugin configuration

Requirements

• Medusa v2
• Node.js >= 20

Installation

yarn add @weareseeed/medusa-athos-plugin

Setup

1. Register the plugin

1// medusa-config.ts
2import { defineConfig } from "@medusajs/framework/config"
3
4export default defineConfig({
5  plugins: [
6    {
7      resolve: "@weareseeed/medusa-athos-plugin",
8      options: {},
9    },
10  ],
11})

2. Run migrations

npx medusa db:migrate

3. Configure via Admin API

Set the plugin configuration through the authenticated admin endpoint:

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

Feed Endpoint

GET /athos/feed?token=<feed_token>

Returns an application/x-ndjson stream. Each product produces:

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

Variant line fields

Product summary line fields

Same as variant line minus all __ private fields, with Product ID set to the product ID and Price set to the lowest price across all variants.

Example

1{"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"}}}
2{"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 medusa-config.ts to extend the feed.

1import { defineConfig } from "@medusajs/framework/config"
2import type { FeedLineContext } from "@weareseeed/medusa-athos-plugin/types"
3
4export default defineConfig({
5  plugins: [
6    {
7      resolve: "@weareseeed/medusa-athos-plugin",
8      options: {
9        feed: {
10          extraProductFields: ["metadata", "variants.metadata"],
11          transformLine: (line, ctx: FeedLineContext) => {
12            line["Brand"] = (ctx.product as any).metadata?.brand ?? undefined
13
14            if (ctx.type === "variant") {
15              line["Custom Variant Field"] = (ctx.variant as any).metadata?.custom ?? undefined
16            }
17
18            if (ctx.type === "product") {
19              line["Custom Product Field"] = (ctx.product as any).metadata?.custom ?? undefined
20            }
21
22            return line
23          },
24        },
25      },
26    },
27  ],
28})

feed.extraProductFields

string[] — Additional Medusa product fields to fetch and make available inside transformLine. Uses the same dot-notation field paths as Medusa's query.graph.

1extraProductFields: [
2  "metadata",
3  "variants.metadata",
4  "images.url",
5  "collection.title",
6]

feed.transformLine

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

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

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

Fields that resolve to undefined are automatically stripped from the output.

Admin API

Both endpoints require an authenticated admin JWT.

License

MIT — Seeed