medusa-plugin-foundry-ims 0.1.0

package/.medusa/server/src/lib/config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Plugin config resolver. Phase 1 reads from env vars only — Phase 2
+ * adds an admin-widget-backed config module that takes precedence.
+ *
+ * Required: FOUNDRY_API_KEY + FOUNDRY_CHANNEL_ID
+ * Optional: FOUNDRY_API_URL (defaults to https://api.foundryims.com)
+ *
+ * If required vars are missing, the plugin becomes a no-op and logs a
+ * one-time warning at startup. We never throw — a missing config must
+ * not break the merchant's order flow.
+ */
+export interface FoundryConfig {
+    apiUrl: string;
+    apiKey: string;
+    channelId: string;
+}
+export declare function resolveConfig(): FoundryConfig | null;

package/.medusa/server/src/lib/config.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Plugin config resolver. Phase 1 reads from env vars only — Phase 2
+ * adds an admin-widget-backed config module that takes precedence.
+ *
+ * Required: FOUNDRY_API_KEY + FOUNDRY_CHANNEL_ID
+ * Optional: FOUNDRY_API_URL (defaults to https://api.foundryims.com)
+ *
+ * If required vars are missing, the plugin becomes a no-op and logs a
+ * one-time warning at startup. We never throw — a missing config must
+ * not break the merchant's order flow.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
+let warnedMissing = false;
+function resolveConfig() {
+    const apiUrl = (process.env.FOUNDRY_API_URL || 'https://api.foundryims.com').replace(/\/$/, '');
+    const apiKey = process.env.FOUNDRY_API_KEY;
+    const channelId = process.env.FOUNDRY_CHANNEL_ID;
+    if (!apiKey || !channelId) {
+        if (!warnedMissing) {
+            // eslint-disable-next-line no-console
+            console.warn('[medusa-plugin-foundry-ims] FOUNDRY_API_KEY and FOUNDRY_CHANNEL_ID must be set ' +
+                'to push events to Foundry. Plugin will no-op until configured.');
+            warnedMissing = true;
+        }
+        return null;
+    }
+    return { apiUrl, apiKey, channelId };
+}

package/.medusa/server/src/lib/foundry-client.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thin client that POSTs Medusa events to Foundry's webhook receiver.
+ *
+ * URL: ${apiUrl}/api/v1/channels/${channelId}/webhook/medusa
+ * Auth: Authorization: Bearer ${apiKey} (Foundry's standard fims_* key)
+ * Body: { topic, payload }
+ *
+ * Errors are logged but never thrown — a Foundry-side blip must not
+ * break the merchant's order checkout. Phase 3 adds a retry queue
+ * with exponential backoff so transient failures don't drop events.
+ */
+declare class FoundryClient {
+    postEvent(topic: string, payload: Record<string, unknown>): Promise<void>;
+}
+export declare const foundryClient: FoundryClient;
+export {};

package/.medusa/server/src/lib/foundry-client.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.foundryClient = void 0;
+const config_1 = require("./config");
+/**
+ * Thin client that POSTs Medusa events to Foundry's webhook receiver.
+ *
+ * URL: ${apiUrl}/api/v1/channels/${channelId}/webhook/medusa
+ * Auth: Authorization: Bearer ${apiKey} (Foundry's standard fims_* key)
+ * Body: { topic, payload }
+ *
+ * Errors are logged but never thrown — a Foundry-side blip must not
+ * break the merchant's order checkout. Phase 3 adds a retry queue
+ * with exponential backoff so transient failures don't drop events.
+ */
+class FoundryClient {
+    async postEvent(topic, payload) {
+        const config = (0, config_1.resolveConfig)();
+        if (!config)
+            return;
+        const url = `${config.apiUrl}/api/v1/channels/${config.channelId}/webhook/medusa`;
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${config.apiKey}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                body: JSON.stringify({ topic, payload }),
+            });
+            if (!response.ok) {
+                // eslint-disable-next-line no-console
+                console.error(`[medusa-plugin-foundry-ims] post failed for ${topic}: ${response.status} ${response.statusText}`);
+            }
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error(`[medusa-plugin-foundry-ims] post error for ${topic}:`, err);
+        }
+    }
+}
+exports.foundryClient = new FoundryClient();

package/.medusa/server/src/subscribers/fulfillment-shipment-created.d.ts

@@ -0,0 +1,15 @@
+import type { SubscriberArgs, SubscriberConfig } from '@medusajs/framework';
+/**
+ * Fires when a fulfillment gets a tracking number — Medusa-side
+ * shipment creation. Foundry's receiver upserts the corresponding
+ * Shipment row so tracking is visible in Foundry's admin without
+ * waiting for the next polling cycle.
+ *
+ * Payload includes order_id; Foundry re-fetches the full order and
+ * walks its shipments[] array.
+ */
+export default function fulfillmentShipmentCreatedHandler({ event: { data }, }: SubscriberArgs<{
+    id: string;
+    order_id: string;
+}>): Promise<void>;
+export declare const config: SubscriberConfig;

package/.medusa/server/src/subscribers/fulfillment-shipment-created.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.default = fulfillmentShipmentCreatedHandler;
+const foundry_client_1 = require("../lib/foundry-client");
+/**
+ * Fires when a fulfillment gets a tracking number — Medusa-side
+ * shipment creation. Foundry's receiver upserts the corresponding
+ * Shipment row so tracking is visible in Foundry's admin without
+ * waiting for the next polling cycle.
+ *
+ * Payload includes order_id; Foundry re-fetches the full order and
+ * walks its shipments[] array.
+ */
+async function fulfillmentShipmentCreatedHandler({ event: { data }, }) {
+    await foundry_client_1.foundryClient.postEvent('fulfillment.shipment_created', {
+        orderId: data.order_id,
+        fulfillmentId: data.id,
+    });
+}
+exports.config = {
+    event: 'fulfillment.shipment_created',
+};

package/.medusa/server/src/subscribers/order-canceled.d.ts

@@ -0,0 +1,10 @@
+import type { SubscriberArgs, SubscriberConfig } from '@medusajs/framework';
+/**
+ * Fires on order cancellation. Foundry's receiver releases all active
+ * reservations on this order — frees up the inventory for other
+ * channels.
+ */
+export default function orderCanceledHandler({ event: { data }, }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const config: SubscriberConfig;

package/.medusa/server/src/subscribers/order-canceled.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.default = orderCanceledHandler;
+const foundry_client_1 = require("../lib/foundry-client");
+/**
+ * Fires on order cancellation. Foundry's receiver releases all active
+ * reservations on this order — frees up the inventory for other
+ * channels.
+ */
+async function orderCanceledHandler({ event: { data }, }) {
+    await foundry_client_1.foundryClient.postEvent('order.canceled', { orderId: data.id });
+}
+exports.config = {
+    event: 'order.canceled',
+};

package/.medusa/server/src/subscribers/order-placed.d.ts

@@ -0,0 +1,12 @@
+import type { SubscriberArgs, SubscriberConfig } from '@medusajs/framework';
+/**
+ * Fires when a customer places an order. We forward a thin envelope
+ * `{ topic: 'order.placed', payload: { orderId } }` to Foundry —
+ * Foundry's receiver re-fetches the full order via its existing
+ * MedusaAdapter so the data flow stays consistent with the cron-poll
+ * path.
+ */
+export default function orderPlacedHandler({ event: { data }, }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const config: SubscriberConfig;

package/.medusa/server/src/subscribers/order-placed.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.default = orderPlacedHandler;
+const foundry_client_1 = require("../lib/foundry-client");
+/**
+ * Fires when a customer places an order. We forward a thin envelope
+ * `{ topic: 'order.placed', payload: { orderId } }` to Foundry —
+ * Foundry's receiver re-fetches the full order via its existing
+ * MedusaAdapter so the data flow stays consistent with the cron-poll
+ * path.
+ */
+async function orderPlacedHandler({ event: { data }, }) {
+    await foundry_client_1.foundryClient.postEvent('order.placed', { orderId: data.id });
+}
+exports.config = {
+    event: 'order.placed',
+};

package/.medusa/server/src/subscribers/order-updated.d.ts

@@ -0,0 +1,10 @@
+import type { SubscriberArgs, SubscriberConfig } from '@medusajs/framework';
+/**
+ * Fires on payment + fulfillment status changes. Foundry's receiver
+ * re-fetches the order, recomputes status, and transitions any active
+ * reservations (commit on shipped/completed, release on refunded).
+ */
+export default function orderUpdatedHandler({ event: { data }, }: SubscriberArgs<{
+    id: string;
+}>): Promise<void>;
+export declare const config: SubscriberConfig;

package/.medusa/server/src/subscribers/order-updated.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.default = orderUpdatedHandler;
+const foundry_client_1 = require("../lib/foundry-client");
+/**
+ * Fires on payment + fulfillment status changes. Foundry's receiver
+ * re-fetches the order, recomputes status, and transitions any active
+ * reservations (commit on shipped/completed, release on refunded).
+ */
+async function orderUpdatedHandler({ event: { data }, }) {
+    await foundry_client_1.foundryClient.postEvent('order.updated', { orderId: data.id });
+}
+exports.config = {
+    event: 'order.updated',
+};

package/README.md

@@ -0,0 +1,113 @@
+# medusa-plugin-foundry-ims
+
+Real-time integration between [Medusa](https://medusajs.com) and [Foundry IMS](https://foundryims.com). Pushes order, inventory, and fulfillment events from your Medusa store to Foundry the moment they happen — replaces polling with native Medusa event subscribers.
+
+## What this plugin does
+
+Subscribes to Medusa events and forwards them to your Foundry workspace:
+
+| Medusa event | What Foundry does |
+|---|---|
+| `order.placed` | Imports the order, creates inventory reservations |
+| `order.updated` | Updates order status, transitions reservations on shipment/refund |
+| `order.canceled` | Releases all active reservations |
+| `fulfillment.shipment_created` | Records the tracking number against the order |
+
+The plugin sends a thin event envelope (`{ topic, payload: { orderId } }`); Foundry refetches the full order from your Medusa admin API for the rest. Your Foundry API key is the auth — no separate webhook secret to manage.
+
+## Requirements
+
+- Medusa **v2.3.0+** (plugin support landed in 2.3.0)
+- Node 20+
+- A Foundry IMS account at [foundryims.com](https://foundryims.com) with:
+  - A `MEDUSA` channel created (Sales Channels → Add Channel → Medusa)
+  - An API key (Settings → API Keys → Create)
+
+## Install
+
+```bash
+npm install medusa-plugin-foundry-ims
+# or
+yarn add medusa-plugin-foundry-ims
+```
+
+In your `medusa-config.ts`:
+
+```ts
+import { defineConfig } from "@medusajs/framework/utils"
+
+module.exports = defineConfig({
+  // ...your existing config...
+  plugins: [
+    {
+      resolve: "medusa-plugin-foundry-ims",
+      options: {},
+    },
+  ],
+})
+```
+
+## Configure
+
+The plugin reads three environment variables:
+
+| Var | Required | Default | Where to get it |
+|---|---|---|---|
+| `FOUNDRY_API_KEY` | yes | — | Foundry → Settings → API Keys → Create. Starts with `fims_`. |
+| `FOUNDRY_CHANNEL_ID` | yes | — | Foundry → Sales Channels → Medusa → URL contains the channel UUID. |
+| `FOUNDRY_API_URL` | no | `https://api.foundryims.com` | Override only for self-hosted or staging Foundry instances. |
+
+Add to your Medusa server's `.env`:
+
+```bash
+FOUNDRY_API_KEY=fims_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+FOUNDRY_CHANNEL_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+Restart your Medusa server. Place a test order — Foundry should receive it within ~1 second.
+
+## Verifying the connection
+
+After a test order:
+
+```bash
+curl -H "Authorization: Bearer $FOUNDRY_API_KEY" \
+  "$FOUNDRY_API_URL/api/v1/orders?limit=5"
+```
+
+You should see your order in the response. If not, check your Medusa logs for `[medusa-plugin-foundry-ims]` warnings — usually a missing env var.
+
+## Troubleshooting
+
+**Plugin warns "FOUNDRY_API_KEY and FOUNDRY_CHANNEL_ID must be set..." on startup.**
+The plugin couldn't find one or both required env vars. Double-check your `.env` and that you've restarted Medusa.
+
+**Orders aren't appearing in Foundry.**
+1. Confirm the API key is valid (curl test above).
+2. Confirm the channel ID matches the one shown in Foundry's URL.
+3. Check Medusa server logs for `[medusa-plugin-foundry-ims] post failed: ...`.
+4. Confirm `orderSyncEnabled` is on for the Foundry channel (Foundry → Sales Channels → Medusa → Settings).
+
+**The plugin works but Foundry shows the wrong status / out-of-date inventory.**
+Foundry refetches via the Medusa admin API on every event. Make sure the `adminApiToken` configured on the Foundry channel is still valid (Settings → Foundry → Sales Channels → Medusa → Edit credentials).
+
+## What this plugin does NOT do
+
+- It does not push *outbound* changes (Foundry → Medusa). That direction is handled by Foundry's existing Medusa adapter.
+- It does not provide an admin UI inside Medusa (yet — coming in v0.2.0).
+- It does not have built-in retry logic for failed posts (yet — coming in v0.3.0). For now, Foundry's 5-minute order-sync cron is the safety net.
+
+## Roadmap
+
+- **v0.2.0** — Admin widget inside Medusa Settings: configure API key + channel ID without env vars.
+- **v0.3.0** — Retry queue for failed event posts. Health-check endpoint. Inventory + product subscribers.
+
+## Support
+
+- [Foundry docs](https://foundryims.com/docs)
+- [GitHub issues](https://github.com/Epic-Design-Labs/medusa-plugin-foundry-ims/issues)
+- [Foundry support email](mailto:support@foundryims.com)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "medusa-plugin-foundry-ims",
+  "version": "0.1.0",
+  "description": "Foundry IMS integration for Medusa — push orders, inventory, and fulfillments to Foundry in real time.",
+  "main": ".medusa/server/src/index.js",
+  "types": ".medusa/server/src/index.d.ts",
+  "files": [
+    ".medusa/server"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./workflows": "./.medusa/server/src/workflows/index.js",
+    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./providers/*": "./.medusa/server/src/providers/*/index.js",
+    "./*": "./.medusa/server/src/*.js",
+    "./admin": {
+      "import": "./.medusa/server/src/admin/index.mjs",
+      "require": "./.medusa/server/src/admin/index.js",
+      "default": "./.medusa/server/src/admin/index.js"
+    }
+  },
+  "keywords": [
+    "medusa-v2",
+    "medusa-plugin-integration",
+    "foundry",
+    "foundry-ims",
+    "inventory",
+    "multichannel",
+    "fulfillment",
+    "order-management"
+  ],
+  "author": "Foundry IMS",
+  "license": "MIT",
+  "homepage": "https://foundryims.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Epic-Design-Labs/medusa-plugin-foundry-ims.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Epic-Design-Labs/medusa-plugin-foundry-ims/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "peerDependencies": {
+    "@medusajs/framework": "^2.3.0",
+    "@medusajs/medusa": "^2.3.0"
+  },
+  "devDependencies": {
+    "@medusajs/admin-sdk": "^2.3.0",
+    "@medusajs/framework": "^2.3.0",
+    "@medusajs/medusa": "^2.3.0",
+    "@medusajs/test-utils": "^2.3.0",
+    "@swc/core": "1.5.7",
+    "typescript": "^5.6.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}