diff --git a/packages/core/types/src/analytics/mutations.ts b/packages/core/types/src/analytics/mutations.ts index 308b5796b5..16bff4054d 100644 --- a/packages/core/types/src/analytics/mutations.ts +++ b/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 } 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 } 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 } -// 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 diff --git a/packages/core/types/src/analytics/provider.ts b/packages/core/types/src/analytics/provider.ts index dc236c408b..40bc1db8e2 100644 --- a/packages/core/types/src/analytics/provider.ts +++ b/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} Resolves when the provider is shutdown successfully. * + * @example + * class MyAnalyticsProviderService extends AbstractAnalyticsProviderService { + * // ... + * async shutdown(): Promise { + * // perform any cleanup or shutdown logic + * // in the analytics provider or using custom logic + * // for example: + * await this.client.shutdown() + * } + * } */ shutdown?(): Promise } diff --git a/packages/core/types/src/analytics/service.ts b/packages/core/types/src/analytics/service.ts index 81cd93f219..01406ce7c1 100644 --- a/packages/core/types/src/analytics/service.ts +++ b/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} 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 /** - * 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} Resolves when the actor or group is identified successfully. * - * * @example * await analyticsModuleService.identify({ * actor_id: "123", diff --git a/packages/core/types/src/file/service.ts b/packages/core/types/src/file/service.ts index d4e15e86c5..64120aa1ae 100644 --- a/packages/core/types/src/file/service.ts +++ b/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 diff --git a/packages/core/utils/src/analytics/abstract-analytics-provider.ts b/packages/core/utils/src/analytics/abstract-analytics-provider.ts index 84529e1571..83494a6c74 100644 --- a/packages/core/utils/src/analytics/abstract-analytics-provider.ts +++ b/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} 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} Resolves when the actor or group is identified successfully. * * @example