feat: Add an analytics module and local and posthog providers (#12505)

* feat: Add an analytics module and local and posthog providers

* fix: Add tests and wire up in missing places

* fix: Address feedback and add missing module typing

* fix: Address feedback and add missing module typing

---------

Co-authored-by: Adrien de Peretti <adrien.deperetti@gmail.com>
Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>

packages/modules/analytics/src/services/analytics-service.ts

@@ -0,0 +1,52 @@
+import {
+  TrackAnalyticsEventDTO,
+  IdentifyAnalyticsEventDTO,
+} from "@medusajs/types"
+import AnalyticsProviderService from "./provider-service"
+import { MedusaError } from "../../../../core/utils/dist/common"
+
+type InjectedDependencies = {
+  analyticsProviderService: AnalyticsProviderService
+}
+
+export default class AnalyticsService {
+  protected readonly analyticsProviderService_: AnalyticsProviderService
+
+  constructor({ analyticsProviderService }: InjectedDependencies) {
+    this.analyticsProviderService_ = analyticsProviderService
+  }
+
+  __hooks = {
+    onApplicationShutdown: async () => {
+      await this.analyticsProviderService_.shutdown()
+    },
+  }
+
+  getProvider() {
+    return this.analyticsProviderService_
+  }
+
+  async track(data: TrackAnalyticsEventDTO): Promise<void> {
+    try {
+      await this.analyticsProviderService_.track(data)
+    } catch (error) {
+      throw new MedusaError(
+        MedusaError.Types.UNEXPECTED_STATE,
+        `Error tracking event for ${data.event}: ${error.message}`
+      )
+    }
+  }
+
+  async identify(data: IdentifyAnalyticsEventDTO): Promise<void> {
+    try {
+      await this.analyticsProviderService_.identify(data)
+    } catch (error) {
+      throw new MedusaError(
+        MedusaError.Types.UNEXPECTED_STATE,
+        `Error identifying event for ${
+          "group" in data ? data.group.id : data.actor_id
+        }: ${error.message}`
+      )
+    }
+  }
+}

packages/modules/analytics/src/services/provider-service.ts

@@ -0,0 +1,56 @@
+import { MedusaError } from "@medusajs/framework/utils"
+import {
+  Constructor,
+  IAnalyticsProvider,
+  ProviderIdentifyAnalyticsEventDTO,
+  ProviderTrackAnalyticsEventDTO,
+} from "@medusajs/types"
+
+export const AnalyticsProviderIdentifierRegistrationName =
+  "analytics_providers_identifier"
+
+export const AnalyticsProviderRegistrationPrefix = "aly_"
+
+type InjectedDependencies = {
+  [
+    key: `${typeof AnalyticsProviderRegistrationPrefix}${string}`
+  ]: IAnalyticsProvider
+}
+
+export default class AnalyticsProviderService {
+  protected readonly analyticsProvider_: IAnalyticsProvider
+
+  constructor(container: InjectedDependencies) {
+    const analyticsProviderKeys = Object.keys(container).filter((k) =>
+      k.startsWith(AnalyticsProviderRegistrationPrefix)
+    )
+
+    if (analyticsProviderKeys.length !== 1) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        `Analytics module should be initialized with exactly one provider`
+      )
+    }
+
+    this.analyticsProvider_ = container[analyticsProviderKeys[0]]
+  }
+
+  static getRegistrationIdentifier(
+    providerClass: Constructor<IAnalyticsProvider>,
+    optionName?: string
+  ) {
+    return `${(providerClass as any).identifier}_${optionName}`
+  }
+
+  async track(data: ProviderTrackAnalyticsEventDTO): Promise<void> {
+    this.analyticsProvider_.track(data)
+  }
+
+  async identify(data: ProviderIdentifyAnalyticsEventDTO): Promise<void> {
+    this.analyticsProvider_.identify(data)
+  }
+
+  async shutdown(): Promise<void> {
+    await this.analyticsProvider_.shutdown?.()
+  }
+}