medusa-stats 1.0.5

package/.medusa/server/src/workflows/statistics/validate-option-configuration.d.ts

@@ -0,0 +1,9 @@
+export interface ValidateOptionConfigurationInput {
+    option_id: string;
+}
+export declare const validateOptionConfigurationWorkflow: import("@medusajs/framework/workflows-sdk").ReturnWorkflow<ValidateOptionConfigurationInput, {
+    isValid: boolean;
+    errors: string[];
+    isComplete: boolean;
+    statDefinition: any;
+}, []>;

package/.medusa/server/src/workflows/statistics/validate-option-configuration.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOptionConfigurationWorkflow = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const fetch_option_with_relations_1 = require("./steps/fetch-option-with-relations");
+const fetch_available_statistics_1 = require("./steps/fetch-available-statistics");
+const validate_option_parameters_1 = require("./steps/validate-option-parameters");
+exports.validateOptionConfigurationWorkflow = (0, workflows_sdk_1.createWorkflow)("validate-option-configuration", (input) => {
+    const option = (0, fetch_option_with_relations_1.fetchOptionWithRelationsStep)({ option_id: input.option_id });
+    const availableStatistics = (0, fetch_available_statistics_1.fetchAvailableStatisticsStep)({});
+    const validation = (0, validate_option_parameters_1.validateOptionParametersStep)({
+        options: [
+            {
+                provider_option_name: option.provider_option_name,
+                local_option_name: option.local_option_name,
+                data: option.data,
+                provider_id: option.provider.id,
+            },
+        ],
+        availableStatistics,
+        partialValidation: false,
+        throwOnError: false,
+    });
+    const result = (0, workflows_sdk_1.transform)(validation, (data) => {
+        const firstResult = data.validationResults[0];
+        return {
+            isValid: firstResult?.isValid ?? false,
+            errors: firstResult?.errors ?? ["Invalid option configuration"],
+            isComplete: firstResult?.isComplete ?? false,
+            statDefinition: firstResult?.statDefinition,
+        };
+    });
+    return new workflows_sdk_1.WorkflowResponse(result);
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsaWRhdGUtb3B0aW9uLWNvbmZpZ3VyYXRpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9zcmMvd29ya2Zsb3dzL3N0YXRpc3RpY3MvdmFsaWRhdGUtb3B0aW9uLWNvbmZpZ3VyYXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEscUVBQWdHO0FBQ2hHLHFGQUFtRjtBQUNuRixtRkFBa0Y7QUFDbEYsbUZBQWtGO0FBTXJFLFFBQUEsbUNBQW1DLEdBQUcsSUFBQSw4QkFBYyxFQUM3RCwrQkFBK0IsRUFDL0IsQ0FBQyxLQUF1QyxFQUFFLEVBQUU7SUFFeEMsTUFBTSxNQUFNLEdBQUcsSUFBQSwwREFBNEIsRUFBQyxFQUFFLFNBQVMsRUFBRSxLQUFLLENBQUMsU0FBUyxFQUFFLENBQUMsQ0FBQztJQUc1RSxNQUFNLG1CQUFtQixHQUFHLElBQUEseURBQTRCLEVBQUMsRUFBRSxDQUFDLENBQUM7SUFHN0QsTUFBTSxVQUFVLEdBQUcsSUFBQSx5REFBNEIsRUFBQztRQUM1QyxPQUFPLEVBQUU7WUFDTDtnQkFDSSxvQkFBb0IsRUFBRSxNQUFNLENBQUMsb0JBQW9CO2dCQUNqRCxpQkFBaUIsRUFBRSxNQUFNLENBQUMsaUJBQWlCO2dCQUMzQyxJQUFJLEVBQUUsTUFBTSxDQUFDLElBQUk7Z0JBQ2pCLFdBQVcsRUFBRSxNQUFNLENBQUMsUUFBUSxDQUFDLEVBQUU7YUFDbEM7U0FDSjtRQUNELG1CQUFtQjtRQUNuQixpQkFBaUIsRUFBRSxLQUFLO1FBQ3hCLFlBQVksRUFBRSxLQUFLO0tBQ3RCLENBQUMsQ0FBQztJQUVILE1BQU0sTUFBTSxHQUFHLElBQUEseUJBQVMsRUFBQyxVQUFVLEVBQUUsQ0FBQyxJQUFJLEVBQUUsRUFBRTtRQUMxQyxNQUFNLFdBQVcsR0FBRyxJQUFJLENBQUMsaUJBQWlCLENBQUMsQ0FBQyxDQUFDLENBQUM7UUFFOUMsT0FBTztZQUNILE9BQU8sRUFBRSxXQUFXLEVBQUUsT0FBTyxJQUFJLEtBQUs7WUFDdEMsTUFBTSxFQUFFLFdBQVcsRUFBRSxNQUFNLElBQUksQ0FBQyw4QkFBOEIsQ0FBQztZQUMvRCxVQUFVLEVBQUUsV0FBVyxFQUFFLFVBQVUsSUFBSSxLQUFLO1lBQzVDLGNBQWMsRUFBRSxXQUFXLEVBQUUsY0FBYztTQUM5QyxDQUFDO0lBQ04sQ0FBQyxDQUFDLENBQUM7SUFFSCxPQUFPLElBQUksZ0NBQWdCLENBQUMsTUFBTSxDQUFDLENBQUM7QUFDeEMsQ0FBQyxDQUNKLENBQUMifQ==

package/README.md

@@ -0,0 +1,310 @@
+<p align="center">
+  <a href="https://www.medusajs.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+  </picture>
+  </a>
+</p>
+
+<h2 align="center">
+  Medusa Stats
+</h2>
+
+<br>
+
+## Overview
+
+`medusa-stats` is a flexible statistics module for Medusa that features:
+
+- Pluggable statistics providers
+- Views, options, and chart composition
+- Composite statistics (statistics depending on other statistics)
+- Statistics-triggered configurable alerts
+- UI interface and admin routes for full statistics lifecycle management
+- Caching for optimized performance
+
+## Installation
+
+```bash
+npm install medusa-stats
+# or
+yarn add medusa-stats
+```
+
+
+
+## Configuration
+
+Add the plugin to your `medusa-config.ts`:
+
+```typescript
+modules: [
+  {
+    resolve: "medusa-stats/modules/statistics",
+    dependencies: [ContainerRegistrationKeys.QUERY], // Query dependency is required in order to be injected into the providers
+    options: {
+      providers: [
+        {
+          resolve: "medusa-stats/providers/common",
+        },
+      ],
+    },
+  },
+],
+plugins: [
+  `medusa-stats`
+]
+```
+
+## Basic Usage
+The plugin provides a framework for defining and calculating statistics as well as an admin interface for their management and visualization. The primary goal of the module is to provide a flexible way to create custom statistics and views that suit your business needs, without being limited to predefined metrics. 
+
+The module can also be used out-of-the-box with pre-defined statistics providers and the admin interface.
+
+### Views
+Views are collections of related statistics visualizations. They allow you to organize statistics in any way that suits your needs. Every chart in a view can display multiple statistical measurements, each based on a different statistic option.
+
+![Views Image](https://github.com/tax1driver/medusa-stats/blob/bf9e67fccc7fb29c2153e4b06194309b6177c12b/public/view.png)
+
+### Options
+Options are instances of statistics that are calculated with specific parameters. By changing an option's parameters, you can adjust the underlying statistic calculation. 
+
+![Options Parameters Image](https://github.com/tax1driver/medusa-stats/blob/bf9e67fccc7fb29c2153e4b06194309b6177c12b/public/params.png)
+
+When editing, options can also be configured in terms of their visualization (chart type, dimensions, etc.), cache settings and other parameters.
+
+![Visualization Settings Image](https://github.com/tax1driver/medusa-stats/blob/bf9e67fccc7fb29c2153e4b06194309b6177c12b/public/visualizations.png)
+
+## Providers
+
+Providers define what statistics are available and how they are calculated.
+
+### Add provider to project
+
+Register your provider in `medusa-config.ts` under the `medusa-stats` module:
+
+```typescript
+modules: [
+  {
+    resolve: "medusa-stats",
+    options: {
+      providers: [
+        { resolve: "medusa-stats/providers/common" },
+        { resolve: "medusa-stats/providers/composite" },
+        { resolve: "./src/providers/statistics/my-provider" },
+      ],
+    },
+  },
+]
+```
+### Included providers
+
+`medusa-stats` includes two built-in providers:
+
+- `medusa-stats/providers/common`
+  - General commerce statistics (orders, carts, sales, channels, regions, and related aggregates).
+- `medusa-stats/providers/composite`
+  - Composite/stat-transform statistics that consume other statistic outputs.
+  - Included statistics: `moving_average`, `rate_of_change`.
+
+
+### Creating a Statistics Provider
+
+Create a provider class by extending `AbstractStatisticsProvider`, expose available statistics in `getAvailableStatistics`, and implement calculation logic in `calculateStatistic`.
+
+Example: a `total_cart_value` statistic (available in the Common Statistics Provider) with filters for currency and cart status.
+
+```typescript
+import { ModuleProvider } from "@medusajs/framework/utils"
+import {
+  AbstractStatisticsProvider,
+  StatBuilder,
+  createTimeSeries,
+  sum,
+  type AvailableStatistic,
+  type CalculateStatisticInput,
+  type StatisticResult,
+} from "medusa-stats"
+
+class MyStatisticsProvider extends AbstractStatisticsProvider {
+  static identifier = "my-statistics"
+  static displayName = "My Statistics Provider"
+
+  async getAvailableStatistics(): Promise<AvailableStatistic[]> {
+    return [
+      new StatBuilder("total_cart_value", "Total Cart Value")
+            .description("Total value of all carts over time")
+            .field({
+                name: "currency_code",
+                label: "Currency",
+                description: "Filter by currency code",
+                schema: z.string().optional(),
+                fieldType: "text",
+                placeholder: "USD"
+            })
+            .chart("line")
+            .dimension("time")
+            .build(),
+    ]
+  }
+
+  async calculateStatistic(input: CalculateStatisticInput): Promise<StatisticResult> {
+    const { id, parameters, periodStart, periodEnd, interval } = input;
+    
+    switch(id) {
+        case "total_cart_value": {
+            const currencyCode = parameters.currency_code;
+
+            const filters: any = {
+                created_at: { $gte: periodStart, $lte: periodEnd }
+            };
+
+            if (currencyCode) {
+                filters.currency_code = currencyCode;
+            }
+
+            const { data: carts } = await this.query.graph({
+                entity: "cart",
+                fields: ["id", "created_at", "total"],
+                filters
+            });
+
+            const timeSeries = createTimeSeries( // helper function for time series creation
+                carts,
+                periodStart,
+                periodEnd,
+                interval,
+                sum('total') // helper accumulator function
+            );
+
+            return {
+                value: timeSeries,
+                metadata: { totalCarts: carts.length }
+            };
+        }
+    }
+  }
+}
+
+export default ModuleProvider("statistics", {
+  services: [MyStatisticsProvider],
+})
+```
+
+
+
+## Composite Statistics
+
+Composite statistics allow one statistic option to use another option's output as an input.
+
+### Admin Usage
+A stat option can be configured to receive another statistic's output by settings its value in the Dependecnies section when editing a stat instance in the admin dashboard.
+
+![Dependencies Image](https://github.com/tax1driver/medusa-stats/blob/bf9e67fccc7fb29c2153e4b06194309b6177c12b/public/composite.png)
+
+### Using composite fields in providers
+
+To make a statistic composable, define a provider parameter with `fieldType: "stat"`.
+At runtime, that parameter receives dependency output data and can be processed like any other input.
+
+```typescript
+import { z } from "zod"
+import { StatBuilder } from "medusa-stats"
+
+new StatBuilder("moving_average", "Moving Average")
+  .description("Smooth a time series by averaging values over a rolling window")
+  .field(
+    {
+      name: "input_series",
+      label: "Input Series",
+      description: "Dependency result to analyze",
+      fieldType: "stat",
+      schema: TimeSeriesSchema
+    }
+  )
+  .field(
+    {
+      name: "window_size",
+      label: "Window Size",
+      fieldType: "number",
+      schema: z.number().int().min(2).max(365).default(7),
+    },
+    7 // initial value
+  )
+  .build()
+```
+
+## Alerts
+
+Alerts can be configured per option to trigger when conditions are met.
+
+### Features
+
+- Absolute and comparative conditions
+- Alert logs
+- Scheduled evaluation job
+- Event emission for custom handling
+
+### Emitted Events
+To handle the alert triggers, register a subscriber for the `statistics.alert` event type. 
+
+```typescript
+type StatisticsAlertEventData = {
+  alert_id: string
+  alert_name: string
+  severity: "info" | "warning" | "critical"
+  option_id: string
+  current_value: number
+  reference_value: number | null
+  compare_value: number | [number, number]
+  operator: "lt" | "gt" | "lte" | "gte" | "eq" | "neq" | "between"
+  comparison_type: string
+}
+```
+
+## Caching
+In order to optimize performance, statistic results are cached for a configurable amount of time. When a statistic is requested, the module first checks if a valid cached result exists and returns it if available. If not, it calculates the statistic, stores the result in the cache, and then returns it.
+
+### Cache Configuration
+To use caching, `CachingModule` must be enabled in the Medusa project.
+
+```typescript
+{
+  resolve: "@medusajs/medusa/caching",
+  options: {
+    providers: [
+      {
+        resolve: "@medusajs/caching-redis",
+        id: "caching-redis",
+        is_default: true,
+        options: {
+          redisUrl: process.env.CACHE_REDIS_URL,
+        },
+      },
+    ],
+  },
+},
+```
+
+The CachingModule's feature flag needs to be enabled as well:
+
+*in `.env` file:*
+```env
+MEDUSA_FF_CACHING=true
+```
+
+or
+
+*in `medusa-config.ts`:*
+```typescript
+featureFlags: {
+  caching: true,
+}
+```
+
+## Planned features and improvements
+- More built-in chart types and visualization options
+- Visualization providers for custom chart types and UI components
+- Visualization on entities' details pages (e.g. product statistics on product page)

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "medusa-stats",
+  "version": "1.0.5",
+  "description": "The most flexible statistics plugin for the most flexible commerce platform.",
+  "author": "Maciej (https://github.com/tax1driver)",
+  "license": "MIT",
+  "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"
+    },
+    ".": {
+      "import": "./.medusa/server/src/index.mjs",
+      "require": "./.medusa/server/src/index.js",
+      "default": "./.medusa/server/src/index.js"
+    }
+  },
+  "keywords": [
+    "medusa",
+    "plugin",
+    "medusa-plugin-stats",
+    "medusa-plugin-metrics",
+    "medusa-plugin",
+    "medusa-v2"
+  ],
+  "scripts": {
+    "build": "medusa plugin:build",
+    "dev": "medusa plugin:develop",
+    "dev:publish": "yarn version patch && medusa plugin:publish",
+    "prepublishOnly": "medusa plugin:build",
+    "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
+    "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
+    "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit"
+  },
+  "devDependencies": {
+    "@medusajs/admin-sdk": "2.12.4",
+    "@medusajs/cli": "2.12.4",
+    "@medusajs/framework": "2.12.4",
+    "@medusajs/icons": "2.12.4",
+    "@medusajs/medusa": "2.12.4",
+    "@medusajs/test-utils": "^2.13.1",
+    "@medusajs/ui": "4.0.25",
+    "@swc/core": "^1.7.28",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.2",
+    "@types/react-dom": "^18.2.25",
+    "@uiw/react-json-view": "^2.0.0-alpha.41",
+    "date-fns": "^4.1.0",
+    "jest": "^30.2.0",
+    "prop-types": "^15.8.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.2",
+    "vite": "^5.2.11",
+    "yalc": "^1.0.0-pre.53"
+  },
+  "peerDependencies": {
+    "@medusajs/admin-sdk": "^2.12.4",
+    "@medusajs/cli": "^2.12.4",
+    "@medusajs/framework": "^2.12.4",
+    "@medusajs/icons": "^2.12.4",
+    "@medusajs/medusa": "^2.12.4",
+    "@medusajs/test-utils": "^2.12.4",
+    "@medusajs/ui": "^4.0.25"
+  },
+  "dependencies": {
+    "react-colorful": "^5.6.1",
+    "recharts": "^3.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "yarn@4.12.0"
+}