medusa-stats 1.0.8 → 1.0.10

package/.medusa/server/src/loaders/statistics/index.js

@@ -44,4 +44,4 @@ const registerProvidersInDb = async ({ container, }) => {
     }
     await financialSummaryService.upsert(upsertData);
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9zcmMvbG9hZGVycy9zdGF0aXN0aWNzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBQUEsdURBQW1GO0FBQ25GLGlFQUFzRTtBQVF0RSxxREFBa0Y7QUFLbEYsbURBQTZEO0FBRTdELE1BQU0seUJBQXlCLEdBQUcsZ0JBQWdCLENBQUE7QUFFbEQsTUFBTSxjQUFjLEdBQUcsS0FBSyxFQUFFLEtBQVUsRUFBRSxTQUEwQixFQUFFLGFBQWtCLEVBQUUsRUFBRTtJQUN4RixJQUFJLENBQUMsS0FBSyxFQUFFLFVBQVUsRUFBRSxDQUFDO1FBQ3JCLE1BQU0sSUFBSSxtQkFBVyxDQUNqQixtQkFBVyxDQUFDLEtBQUssQ0FBQyxnQkFBZ0IsRUFDbEMseUVBQXlFLENBQzVFLENBQUE7SUFDTCxDQUFDO0lBRUQsTUFBTSxHQUFHLEdBQUcsTUFBTSxLQUFLLENBQUMsVUFBVSxHQUFHLGFBQWEsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLElBQUksYUFBYSxDQUFDLEVBQUUsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUM3RSxFQUFFLENBQUE7SUFLTixTQUFTLENBQUMsUUFBUSxDQUFDO1FBQ2YsQ0FBQyxHQUFHLENBQUMsRUFBRSxJQUFBLGdCQUFPLEVBQUMsS0FBSyxDQUFDO0tBQ3hCLENBQUMsQ0FBQztJQUlILGtCQUFNLENBQUMsSUFBSSxDQUFDLG1DQUFtQyxLQUFLLENBQUMsVUFBVSxjQUFjLEdBQUcsRUFBRSxDQUFDLENBQUM7SUFDcEYsU0FBUyxDQUFDLFdBQVcsQ0FBQyx5QkFBeUIsRUFBRSxJQUFBLGdCQUFPLEVBQUMsRUFBRSxFQUFFLEVBQUUsR0FBRyxFQUFFLFlBQVksRUFBRSxLQUFLLENBQUMsV0FBVyxJQUFJLEtBQUssQ0FBQyxVQUFVLEVBQUUsQ0FBQyxDQUFDLENBQUE7QUFDL0gsQ0FBQyxDQUFBO0FBRUQsa0JBQWUsS0FBSyxFQUFFLEVBQ2xCLFNBQVMsRUFDVCxPQUFPLEdBUVYsRUFBaUIsRUFBRTtJQUNoQixNQUFNLElBQUEsa0NBQW9CLEVBQUM7UUFDdkIsU0FBUztRQUNULFNBQVMsRUFBRSxPQUFPLEVBQUUsU0FBUyxJQUFJLEVBQUU7UUFDbkMsaUJBQWlCLEVBQUUsY0FBYztLQUNwQyxDQUFDLENBQUE7SUFFRixNQUFNLHFCQUFxQixDQUFDLEVBQUUsU0FBUyxFQUFFLENBQUMsQ0FBQTtBQUM5QyxDQUFDLENBQUE7QUFFRCxNQUFNLHFCQUFxQixHQUFHLEtBQUssRUFBRSxFQUNqQyxTQUFTLEdBQ0csRUFBaUIsRUFBRTtJQUMvQixNQUFNLGVBQWUsR0FBRyxTQUFTLENBQUMsT0FBTyxDQUF5Qyx5QkFBeUIsRUFBRTtRQUN6RyxpQkFBaUIsRUFBRSxJQUFJO0tBQzFCLENBQUMsQ0FBQTtJQUVGLElBQUksQ0FBQyxlQUFlLEVBQUUsTUFBTSxFQUFFLENBQUM7UUFDM0IsT0FBTTtJQUNWLENBQUM7SUFFRCxNQUFNLHVCQUF1QixHQUFHLFNBQVMsQ0FBQyxPQUFPLENBQzdDLDJCQUEyQixDQUM5QixDQUFDO0lBRUYsTUFBTSxpQkFBaUIsR0FBRyxNQUFNLHVCQUF1QixDQUFDLElBQUksQ0FDeEQsRUFBRSxFQUFFLEVBQUUsZUFBZSxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsRUFBRSxFQUN0QyxFQUFFLENBQ0wsQ0FBQTtJQUVELE1BQU0sVUFBVSxHQUFnRSxFQUFFLENBQUE7SUFFbEYsS0FBSyxNQUFNLEVBQUUsRUFBRSxFQUFFLFlBQVksRUFBRSxJQUFJLGlCQUFpQixFQUFFLENBQUM7UUFDbkQsSUFBSSxDQUFDLGVBQWUsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLENBQUM7WUFDMUMsVUFBVSxDQUFDLElBQUksQ0FBQyxFQUFFLEVBQUUsRUFBRSxVQUFVLEVBQUUsS0FBSyxFQUFFLFlBQVksRUFBRSxDQUFDLENBQUE7UUFDNUQsQ0FBQztJQUNMLENBQUM7SUFFRCxLQUFLLE1BQU0sRUFBRSxFQUFFLEVBQUUsWUFBWSxFQUFFLElBQUksZUFBZSxFQUFFLENBQUM7UUFDakQsVUFBVSxDQUFDLElBQUksQ0FBQyxFQUFFLEVBQUUsRUFBRSxVQUFVLEVBQUUsSUFBSSxFQUFFLFlBQVksRUFBRSxDQUFDLENBQUE7SUFDM0QsQ0FBQztJQUVELE1BQU0sdUJBQXVCLENBQUMsTUFBTSxDQUFDLFVBQVUsQ0FBQyxDQUFBO0FBQ3BELENBQUMsQ0FBQSJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9zcmMvbG9hZGVycy9zdGF0aXN0aWNzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBQUEsdURBQW1GO0FBQ25GLGlFQUFzRTtBQVF0RSxxREFBa0Y7QUFLbEYsbURBQTZEO0FBRTdELE1BQU0seUJBQXlCLEdBQUcsZ0JBQWdCLENBQUE7QUFFbEQsTUFBTSxjQUFjLEdBQUcsS0FBSyxFQUFFLEtBQVUsRUFBRSxTQUEwQixFQUFFLGFBQWtCLEVBQUUsRUFBRTtJQUN4RixJQUFJLENBQUMsS0FBSyxFQUFFLFVBQVUsRUFBRSxDQUFDO1FBQ3JCLE1BQU0sSUFBSSxtQkFBVyxDQUNqQixtQkFBVyxDQUFDLEtBQUssQ0FBQyxnQkFBZ0IsRUFDbEMseUVBQXlFLENBQzVFLENBQUE7SUFDTCxDQUFDO0lBRUQsTUFBTSxHQUFHLEdBQUcsTUFBTSxLQUFLLENBQUMsVUFBVSxHQUFHLGFBQWEsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLElBQUksYUFBYSxDQUFDLEVBQUUsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLEVBQUUsQ0FBQztJQUV0RixTQUFTLENBQUMsUUFBUSxDQUFDO1FBQ2YsQ0FBQyxHQUFHLENBQUMsRUFBRSxJQUFBLGdCQUFPLEVBQUMsS0FBSyxDQUFDO0tBQ3hCLENBQUMsQ0FBQztJQUlILGtCQUFNLENBQUMsSUFBSSxDQUFDLG1DQUFtQyxLQUFLLENBQUMsVUFBVSxjQUFjLEdBQUcsRUFBRSxDQUFDLENBQUM7SUFDcEYsU0FBUyxDQUFDLFdBQVcsQ0FBQyx5QkFBeUIsRUFBRSxJQUFBLGdCQUFPLEVBQUMsRUFBRSxFQUFFLEVBQUUsR0FBRyxFQUFFLFlBQVksRUFBRSxLQUFLLENBQUMsV0FBVyxJQUFJLEtBQUssQ0FBQyxVQUFVLEVBQUUsQ0FBQyxDQUFDLENBQUE7QUFDL0gsQ0FBQyxDQUFBO0FBRUQsa0JBQWUsS0FBSyxFQUFFLEVBQ2xCLFNBQVMsRUFDVCxPQUFPLEdBUVYsRUFBaUIsRUFBRTtJQUNoQixNQUFNLElBQUEsa0NBQW9CLEVBQUM7UUFDdkIsU0FBUztRQUNULFNBQVMsRUFBRSxPQUFPLEVBQUUsU0FBUyxJQUFJLEVBQUU7UUFDbkMsaUJBQWlCLEVBQUUsY0FBYztLQUNwQyxDQUFDLENBQUE7SUFFRixNQUFNLHFCQUFxQixDQUFDLEVBQUUsU0FBUyxFQUFFLENBQUMsQ0FBQTtBQUM5QyxDQUFDLENBQUE7QUFFRCxNQUFNLHFCQUFxQixHQUFHLEtBQUssRUFBRSxFQUNqQyxTQUFTLEdBQ0csRUFBaUIsRUFBRTtJQUMvQixNQUFNLGVBQWUsR0FBRyxTQUFTLENBQUMsT0FBTyxDQUF5Qyx5QkFBeUIsRUFBRTtRQUN6RyxpQkFBaUIsRUFBRSxJQUFJO0tBQzFCLENBQUMsQ0FBQTtJQUVGLElBQUksQ0FBQyxlQUFlLEVBQUUsTUFBTSxFQUFFLENBQUM7UUFDM0IsT0FBTTtJQUNWLENBQUM7SUFFRCxNQUFNLHVCQUF1QixHQUFHLFNBQVMsQ0FBQyxPQUFPLENBQzdDLDJCQUEyQixDQUM5QixDQUFDO0lBRUYsTUFBTSxpQkFBaUIsR0FBRyxNQUFNLHVCQUF1QixDQUFDLElBQUksQ0FDeEQsRUFBRSxFQUFFLEVBQUUsZUFBZSxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsRUFBRSxFQUN0QyxFQUFFLENBQ0wsQ0FBQTtJQUVELE1BQU0sVUFBVSxHQUFnRSxFQUFFLENBQUE7SUFFbEYsS0FBSyxNQUFNLEVBQUUsRUFBRSxFQUFFLFlBQVksRUFBRSxJQUFJLGlCQUFpQixFQUFFLENBQUM7UUFDbkQsSUFBSSxDQUFDLGVBQWUsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLENBQUM7WUFDMUMsVUFBVSxDQUFDLElBQUksQ0FBQyxFQUFFLEVBQUUsRUFBRSxVQUFVLEVBQUUsS0FBSyxFQUFFLFlBQVksRUFBRSxDQUFDLENBQUE7UUFDNUQsQ0FBQztJQUNMLENBQUM7SUFFRCxLQUFLLE1BQU0sRUFBRSxFQUFFLEVBQUUsWUFBWSxFQUFFLElBQUksZUFBZSxFQUFFLENBQUM7UUFDakQsVUFBVSxDQUFDLElBQUksQ0FBQyxFQUFFLEVBQUUsRUFBRSxVQUFVLEVBQUUsSUFBSSxFQUFFLFlBQVksRUFBRSxDQUFDLENBQUE7SUFDM0QsQ0FBQztJQUVELE1BQU0sdUJBQXVCLENBQUMsTUFBTSxDQUFDLFVBQVUsQ0FBQyxDQUFBO0FBQ3BELENBQUMsQ0FBQSJ9

package/README.md

@@ -1,310 +1,317 @@
-<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)
+<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>
+
+<h5 align="center">
+  <a href="https://docs.medusajs.com">MedusaJS</a> |
+  <a href="https://www.npmjs.com/package/medusa-stats">npm</a> |
+  <a href="https://github.com/tax1driver/medusa-stats">Repository</a>
+</h5>
+
+
+<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/master/docs/static/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/master/docs/static/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/master/docs/static/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/master/docs/static/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

@@ -1,88 +1,92 @@
-{
-  "name": "medusa-stats",
-  "version": "1.0.8",
-  "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-plugin-analytics",
-    "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"
-}
+{
+  "name": "medusa-stats",
+  "version": "1.0.10",
+  "description": "The most flexible statistics plugin for the most flexible commerce platform.",
+  "author": "Maciej (https://github.com/tax1driver)",
+  "license": "MIT",
+  "files": [
+    ".medusa/server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tax1driver/medusa-stats.git"
+  },
+  "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-plugin-analytics",
+    "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"
+}