chore(types, utils): update TSDocs related to analytics module (#12564)

packages/core/types/src/analytics/mutations.ts

@@ -9,31 +9,65 @@ export interface TrackAnalyticsEventDTO {
   actor_id?: string
   /**
    * The group that the event is for, such as an organization or team.
-   * The "type" defines the name of the group (eg. "organization"), and the "id" is the id of the group.
    */
   group?: {
+    /**
+     * The name of the group.
+     * 
+     * @example
+     * "organization"
+     */
     type?: string
+    /**
+     * The group's ID.
+     */
     id?: string
   }
   /**
-   * The properties of the event. The format and content depends on the provider.
+   * The properties of the event. The format and content is dynamic and depends on the integrated provider.
    */
   properties?: Record<string, any>
 }
 
 export interface IdentifyActorDTO {
+  /**
+   * The actor of the event, if there is any.
+   */
   actor_id: string
+  /**
+   * The properties of the actor. The format and content is dynamic and depends on the integrated provider.
+   */
   properties?: Record<string, any>
 }
 
 export interface IdentifyGroupDTO {
+  /**
+   * The group that the event is for, such as an organization or team.
+   */
   group: {
+    /**
+     * The name of the group.
+     * 
+     * @example
+     * "organization"
+     */
     type: string
+    /**
+     * The group's ID.
+     */
     id: string
   }
-  // When identifying a group, the actor can potentially be passed as well as metadata.
+  /**
+   * When identifying a group, the actor can potentially be passed as well as metadata.
+   */
   actor_id?: string
+  /**
+   * The properties of the group. The format and content is dynamic and depends on the integrated provider.
+   */
   properties?: Record<string, any>
 }
-// Either actor_id or group must be provided. Depending on the provided identifier, the properties will be set for the actor or group.
+
+/**
+ * Either the `actor_id` or the `group` property must be set.
+ */
 export type IdentifyAnalyticsEventDTO = IdentifyActorDTO | IdentifyGroupDTO

packages/core/types/src/analytics/provider.ts

@@ -25,9 +25,21 @@ export interface IAnalyticsProvider {
 
   /**
    * This method is used to shutdown the analytics provider, and flush all data before shutting down.
+   * 
+   * This method is called by the Analytics Module when the Medusa application is shutting down.
    *
    * @returns {Promise<void>} Resolves when the provider is shutdown successfully.
    *
+   * @example
+   * class MyAnalyticsProviderService extends AbstractAnalyticsProviderService {
+   *   // ...
+   *   async shutdown(): Promise<void> {
+   *     // perform any cleanup or shutdown logic
+   *     // in the analytics provider or using custom logic
+   *     // for example:
+   *     await this.client.shutdown()
+   *   }
+   * }
    */
   shutdown?(): Promise<void>
 }

packages/core/types/src/analytics/service.ts

@@ -4,35 +4,43 @@ import { IAnalyticsProvider } from "./provider"
 
 export interface IAnalyticsModuleService extends IModuleService {
   /**
-   * Returns a reference to the analytics provider in use
+   * This method returns the service of the configured Analytics Module Provider in `medusa-config.ts`. This is useful
+   * if you want to execute custom methods defined in the provider's service or you need direct access to it.
+   * 
+   * @returns {IAnalyticsProvider} An instance of the Analytics Module Provider's service.
+   * 
+   * @example
+   * const postHogProviderService = analyticsModuleService.getProvider()
+   * // TODO: perform custom actions with the provider
    */
   getProvider(): IAnalyticsProvider
 
   /**
-   * This method tracks an event in the analytics provider
+   * This method tracks an event in the analytics provider. The Analytics Module
+   * will use the `track` method of the underlying provider configured in `medusa-config.ts` to track the event.
    *
-   * @param {TrackAnalyticsEventDTO} data - The data for the event.
+   * @param {TrackAnalyticsEventDTO} data - The event's details.
    * @returns {Promise<void>} Resolves when the event is tracked successfully.
    *
-   *
    * @example
    * await analyticsModuleService.track({
-   *   event: "product_viewed",
+   *   event: "order_placed",
    *   properties: {
-   *     product_id: "123",
-   *     product_name: "Product Name"
+   *     order_id: "order_123",
+   *     customer_id: "customer_456",
+   *     total: 100,
    *   }
    * })
    */
   track(data: TrackAnalyticsEventDTO): Promise<void>
 
   /**
-   * This method identifies an actor or group in the analytics provider
+   * This method identifies an actor or group in the analytics provider. The Analytics Module
+   * will use the `identify` method of the underlying provider configured in `medusa-config.ts` to identify the actor or group.
    *
-   * @param {IdentifyAnalyticsEventDTO} data - The data for the actor or group.
+   * @param {IdentifyAnalyticsEventDTO} data - The details of the actor or group.
    * @returns {Promise<void>} Resolves when the actor or group is identified successfully.
    *
-   *
    * @example
    * await analyticsModuleService.identify({
    *   actor_id: "123",

packages/core/types/src/file/service.ts

@@ -8,7 +8,14 @@ import { CreateFileDTO, GetUploadFileUrlDTO } from "./mutations"
 
 export interface IFileModuleService extends IModuleService {
   /**
-   * Returns a reference to the file provider in use
+   * This method returns the service of the configured File Module Provider in `medusa-config.ts`. This is useful
+   * if you want to execute custom methods defined in the provider's service or you need direct access to it.
+   * 
+   * @returns {IFileProvider} An instance of the File Module Provider's service.
+   * 
+   * @example
+   * const s3ProviderService = fileModuleService.getProvider()
+   * // TODO: perform custom actions with the provider
    */
   getProvider(): IFileProvider
 

packages/core/utils/src/analytics/abstract-analytics-provider.ts

@@ -72,11 +72,12 @@ export class AbstractAnalyticsProviderService implements IAnalyticsProvider {
   }
 
   /**
-   * This method tracks an event using your provider's semantics
+   * This method tracks an event with the third-party analytics provider. The Analytics Module
+   * will use this method in its `track` method if your provider is configured in `medusa-config.ts`.
+   * 
+   * You can send the event to the third-party provider based on its semantics.
    *
-   * This method will be used when tracking events to third-party providers.
-   *
-   * @param {ProviderTrackAnalyticsEventDTO} data - The data for the event.
+   * @param {ProviderTrackAnalyticsEventDTO} data - The event's details.
    * @returns {Promise<void>} Resolves when the event is tracked successfully.
    *
    * @example
@@ -97,9 +98,10 @@ export class AbstractAnalyticsProviderService implements IAnalyticsProvider {
   }
 
   /**
-   * This method identifies an actor or group in the analytics provider
+   * This method identifies an actor or group in the third-party analytics provider. The Analytics Module
+   * will use this method in its `identify` method if your provider is configured in `medusa-config.ts`.
    *
-   * @param {ProviderIdentifyAnalyticsEventDTO} data - The data for the actor or group.
+   * @param {ProviderIdentifyAnalyticsEventDTO} data - The details of the actor or group.
    * @returns {Promise<void>} Resolves when the actor or group is identified successfully.
    *
    * @example