@medusajs/analytics 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +73 -0
  2. package/README.md +95 -1
  3. package/package.json +8 -4
package/AGENTS.md ADDED
@@ -0,0 +1,73 @@
1
+ # @medusajs/analytics
2
+
3
+ Analytics Module (`Modules.ANALYTICS`). A thin, provider-based facade that forwards `track` / `identify` calls to exactly one Analytics Module Provider (Local, PostHog, or custom). It has no data models and is not registered by default.
4
+
5
+ ## Using this package
6
+
7
+ - Install path consumers use: `@medusajs/medusa/analytics` (re-export of this package). Providers: `@medusajs/medusa/analytics-local`, `@medusajs/medusa/analytics-posthog`.
8
+ - Register in `medusa-config.ts` (not part of `defineConfig` defaults):
9
+
10
+ ```ts
11
+ module.exports = defineConfig({
12
+ modules: [
13
+ {
14
+ resolve: "@medusajs/medusa/analytics",
15
+ options: {
16
+ providers: [
17
+ {
18
+ resolve: "@medusajs/medusa/analytics-local",
19
+ id: "local",
20
+ },
21
+ ],
22
+ },
23
+ },
24
+ ],
25
+ })
26
+ ```
27
+
28
+ - Module options (`AnalyticsModuleOptions` in `src/types/index.ts`): `providers: { resolve, id, options? }[]`. `options` is passed as the provider constructor's second argument.
29
+ - Resolve and use (typically inside a workflow step):
30
+
31
+ ```ts
32
+ const analytics = container.resolve(Modules.ANALYTICS)
33
+
34
+ await analytics.track({
35
+ event: "order_placed",
36
+ actor_id: order.customer_id,
37
+ properties: { order_id: order.id },
38
+ })
39
+
40
+ await analytics.identify({ actor_id: customer.id, properties: { email } })
41
+ // or group identify:
42
+ await analytics.identify({ group: { type: "company", id }, properties })
43
+ ```
44
+
45
+ - Service methods (`src/services/analytics-service.ts`): `track(data)`, `identify(data)`, `getProvider()` (returns the internal provider service). No generated CRUD methods, no events emitted, no module links.
46
+ - Custom providers extend `AbstractAnalyticsProviderService` from `@medusajs/framework/utils` and implement `track`, `identify`, and optionally `shutdown`.
47
+ - Docs: https://docs.medusajs.com/resources/infrastructure-modules/analytics.md, https://docs.medusajs.com/resources/infrastructure-modules/analytics/local.md, https://docs.medusajs.com/resources/infrastructure-modules/analytics/posthog.md
48
+
49
+ ## Architecture
50
+
51
+ - `src/index.ts`: `Module(Modules.ANALYTICS, { service: AnalyticsService, loaders: [loadProviders] })`.
52
+ - `src/loaders/providers.ts`: registers each provider in the module container as `aly_<identifier>_<id>` (via `ProviderService.getRegistrationIdentifier`) and appends the key to `analytics_providers_identifier`.
53
+ - `src/services/provider-service.ts` (`AnalyticsProviderService`): picks up the single container key starting with `aly_` and delegates to it.
54
+ - `src/services/analytics-service.ts`: wraps provider errors in `MedusaError(UNEXPECTED_STATE, "Error tracking event for <event>: ...")` / `"Error identifying event for <id>: ..."`.
55
+ - `src/types/index.ts` augments `ModuleOptions` for both `@medusajs/analytics` and `@medusajs/medusa/analytics`.
56
+
57
+ ## Development
58
+
59
+ ```bash
60
+ yarn build
61
+ yarn test # unit tests under src (none currently)
62
+ yarn test:integration # integration-tests/__tests__/module.spec.ts
63
+ yarn test:integration -t "<test name>"
64
+ ```
65
+
66
+ - Integration tests use `moduleIntegrationTestRunner` with a fixture provider in `integration-tests/__fixtures__/providers/default-provider.ts`, spied with `jest.spyOn`.
67
+ - No models, so there is no `migration:create` script and no migrations.
68
+
69
+ ## Gotchas
70
+
71
+ - Exactly one provider is required: `AnalyticsProviderService` throws `INVALID_DATA` ("Analytics module should be initialized with exactly one provider") with zero or more than one. There is no `is_default` / per-call provider selection.
72
+ - Provider shutdown runs through the service's `__hooks.onApplicationShutdown`, calling the provider's optional `shutdown()` (used by PostHog to flush).
73
+ - Provider classes must define a static `identifier`; the registration key is built from it (`aly_<identifier>_<id>`) and nothing validates it is set.
package/README.md CHANGED
@@ -1 +1,95 @@
1
- # Analytics Module
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/analytics
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ Analytics Module for Medusa: tracks events and identifies users by forwarding them to third-party analytics services such as PostHog. It uses a provider pattern, so the service you send data to is a pluggable Analytics Module Provider. It ships with `@medusajs/medusa` and is registered from `@medusajs/medusa/analytics`.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/analytics` |
44
+ | Type | Infrastructure Module |
45
+ | Module key | `Modules.ANALYTICS` (`"analytics"`) |
46
+ | Registered by default | No |
47
+ | Import from | `@medusajs/medusa/analytics` |
48
+
49
+ ## Features
50
+
51
+ - Track events (for example, order placed) and identify users from workflows, subscribers, or API routes.
52
+ - Pluggable providers. Official providers:
53
+ - [`@medusajs/analytics-local`](../providers/analytics-local): logs events with the Medusa logger, for development.
54
+ - [`@medusajs/analytics-posthog`](../providers/analytics-posthog): sends events to PostHog.
55
+
56
+ ## Installation
57
+
58
+ No installation needed. The module ships with `@medusajs/medusa`, but you must register it in `medusa-config.ts`.
59
+
60
+ ## Usage
61
+
62
+ ```ts title="medusa-config.ts"
63
+ import { defineConfig } from "@medusajs/framework/utils"
64
+
65
+ module.exports = defineConfig({
66
+ // ...
67
+ modules: [
68
+ {
69
+ resolve: "@medusajs/medusa/analytics",
70
+ options: {
71
+ providers: [
72
+ {
73
+ resolve: "@medusajs/medusa/analytics-local",
74
+ id: "local",
75
+ },
76
+ ],
77
+ },
78
+ },
79
+ ],
80
+ })
81
+ ```
82
+
83
+ Then resolve the service with `container.resolve(Modules.ANALYTICS)` and call its `track` and `identify` methods.
84
+
85
+ ## Configuration
86
+
87
+ | Option | Type | Description | Default |
88
+ | --- | --- | --- | --- |
89
+ | `providers` | `{ resolve: string, id: string, options?: Record<string, unknown> }[]` | Analytics Module Providers to register. `options` is passed to the provider. | `[]` |
90
+
91
+ ## Resources
92
+
93
+ - [Analytics Module](https://docs.medusajs.com/resources/infrastructure-modules/analytics)
94
+ - [Local Analytics Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/analytics/local)
95
+ - [PostHog Analytics Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/analytics/posthog)
package/package.json CHANGED
@@ -1,15 +1,19 @@
1
1
  {
2
2
  "name": "@medusajs/analytics",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Medusa Analytics module",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "files": [
8
8
  "dist",
9
+ "AGENTS.md",
9
10
  "!dist/**/__tests__",
10
11
  "!dist/**/__mocks__",
11
12
  "!dist/**/__fixtures__"
12
13
  ],
14
+ "llms": "https://docs.medusajs.com/llms.txt",
15
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
16
+ "mcpServer": "https://docs.medusajs.com/mcp",
13
17
  "engines": {
14
18
  "node": ">=22.22.0"
15
19
  },
@@ -35,10 +39,10 @@
35
39
  "test:integration": "../../../node_modules/.bin/jest --passWithNoTests --forceExit --testPathPattern=\"integration-tests/__tests__/.*\\.ts\""
36
40
  },
37
41
  "devDependencies": {
38
- "@medusajs/framework": "2.22.0-snapshot-20261020204851",
39
- "@medusajs/test-utils": "2.22.0-snapshot-20261020204851"
42
+ "@medusajs/framework": "2.22.0",
43
+ "@medusajs/test-utils": "2.22.0"
40
44
  },
41
45
  "peerDependencies": {
42
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
46
+ "@medusajs/framework": "2.22.0"
43
47
  }
44
48
  }