stock-monitoring

v0.0.6

Published

3 months ago

Monitor product inventory levels and send email notifications for low stock, out of stock, and slow-moving products.

0High
0Medium
0Low

pradip1995

medusa plugin medusa-plugin-other medusa-plugin medusa-v2

stock-monitoring

Medusa v2 plugin that monitors inventory levels (low, out-of-stock, and slow-moving) and sends admin notification alerts.

Plugin Overview

stock-monitoring adds stock alert monitoring to Medusa by:

Evaluating inventory quantities per variant and per warehouse/location level.
Detecting three alert types:
- low_stock
- out_of_stock
- slow_moving
Running a scheduled daily stock check job.
Sending notification emails to configured admin recipients via Medusa notification module.
Exposing an admin API for listing/filtering alerts.
Providing an admin route page for alert visualization and filtering.

This plugin is built for Medusa v2 (uses Medusa module/workflow/job/admin-sdk APIs).

Installation & Setup

1) Install package

npm install stock-monitoring
# or
yarn add stock-monitoring

2) Register in `medusa-config.ts`

import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  modules: {
    stock_monitoring: {
      resolve: "stock-monitoring",
      options: {
        low_stock_threshold: 10,
        slow_moving_days_threshold: 90,
        low_stock_threshold_per_warehouse: {
          // "sloc_...": 5
        },
        admin_notification_emails: ["[email protected]"],
      },
    },
  },
  plugins: [
    {
      resolve: "stock-monitoring",
      options: {
        low_stock_threshold: 10,
        slow_moving_days_threshold: 90,
        low_stock_threshold_per_warehouse: {},
        admin_notification_emails: ["[email protected]"],
      },
    },
  ],
})

3) Migrations

No plugin-specific database models/migrations are defined in this codebase.

You can still run standard app migrations as usual:

npx medusa db:migrate

Configuration (`config.ts` / plugin options)

Configuration is defined by StockMonitoringPluginOptions (src/types/stock-monitoring.ts) and validated in src/modules/stock-monitoring/service.ts.

| Option | Type | Required | Default | Description | |---|---|---|---|---| | low_stock_threshold | number | Optional | 10 | Global threshold used for low-stock alerts. | | slow_moving_days_threshold | number | Optional | 90 | Days-since-update threshold for slow-moving alerts. | | low_stock_threshold_per_warehouse | Record<string, number> | Optional | {} | Per-location threshold override keyed by location_id. | | admin_notification_emails | string[] | Optional | [] | Recipients for stock alert notifications. If empty, job skips sending notifications. |

Validation behavior:

Thresholds must be integers and >= 0.
Email list must be an array of strings; empty/whitespace entries are ignored.

Complete example config block

{
  modules: {
    stock_monitoring: {
      resolve: "stock-monitoring",
      options: {
        low_stock_threshold: 12,
        slow_moving_days_threshold: 120,
        low_stock_threshold_per_warehouse: {
          sloc_warehouse_a: 5,
          sloc_warehouse_b: 20,
        },
        admin_notification_emails: [
          "[email protected]",
          "[email protected]",
        ],
      },
    },
  },
  plugins: [
    {
      resolve: "stock-monitoring",
      options: {
        low_stock_threshold: 12,
        slow_moving_days_threshold: 120,
        low_stock_threshold_per_warehouse: {
          sloc_warehouse_a: 5,
          sloc_warehouse_b: 20,
        },
        admin_notification_emails: [
          "[email protected]",
          "[email protected]",
        ],
      },
    },
  ],
}

Environment Variables

No runtime process.env.* usage is present in this plugin’s src code.

| Variable | Used in src runtime code? | Notes | |---|---|---| | None | No | All plugin behavior is configured through Medusa module/plugin options. |

REST APIs / Routes

Admin APIs

`GET /admin/stock-monitoring/alerts`

Auth requirement: Admin JWT (admin namespace route)
Query params:

| Param | Type | Required | Default | Notes | |---|---|---|---|---| | limit | number string | No | 50 | Clamped to 1..200. | | offset | number string | No | 0 | Min 0. | | alert_type | enum | No | — | low_stock, out_of_stock, slow_moving. | | product_id | string | No | — | Exact product id filter. | | variant_id | string | No | — | Exact variant id filter. | | search | string | No | — | Case-insensitive title search (product or variant). |

Response schema:

| Field | Type | |---|---| | alerts | StockAlertInput[] | | count | number | | limit | number | | offset | number |

StockAlertInput includes:

variant_id
product_id
product_title
variant_title
current_quantity
alert_type
optional threshold
optional days_unchanged
optional location_id
optional location_name
Description: Computes current alert list from product + inventory queries, applies filters, returns paginated results.

Health routes

GET /admin/plugin -> 200
GET /store/plugin -> 200

Important endpoint examples

# List alerts (first page)
curl "http://localhost:9000/admin/stock-monitoring/alerts?limit=50&offset=0" \
  -H "Authorization: Bearer <ADMIN_JWT>"

# Filter by out-of-stock alerts
curl "http://localhost:9000/admin/stock-monitoring/alerts?alert_type=out_of_stock" \
  -H "Authorization: Bearer <ADMIN_JWT>"

# Search by title
curl "http://localhost:9000/admin/stock-monitoring/alerts?search=laptop" \
  -H "Authorization: Bearer <ADMIN_JWT>"

Services