AbstractNotificationService

Overview

Prerequisites

Before creating a Notification Provider, install an event bus module.

A Notification Provider is a provider that handles sending and resending of notifications.

To create a Notification Provider, create a TypeScript or JavaScript file in src/services. The name of the file is the name of the provider (for example, sendgrid.ts). The file must export a class that extends the AbstractNotificationService class imported from @medusajs/medusa.

For example, create the file src/services/email-sender.ts with the following content:

src/services/email-sender.ts

import { AbstractNotificationService } from "@medusajs/medusa"
import { EntityManager } from "typeorm"

class EmailSenderService extends AbstractNotificationService {
  protected manager_: EntityManager
  protected transactionManager_: EntityManager

  sendNotification(
    event: string,
    data: unknown,
    attachmentGenerator: unknown
  ): Promise<{
      to: string;
      status: string;
      data: Record<string, unknown>;
    }> {
    throw new Error("Method not implemented.")
  }
  resendNotification(
    notification: unknown,
    config: unknown,
    attachmentGenerator: unknown
  ): Promise<{
      to: string;
      status: string;
      data: Record<string, unknown>;
    }> {
    throw new Error("Method not implemented.")
  }

}

export default EmailSenderService

---

Identifier Property

The NotificationProvider entity has 2 properties: identifier and is_installed. The value of the identifier property in the notification provider class is used when the Notification Provider is created in the database.

The value of this property is also used later when you want to subscribe the Notification Provider to events in a Loader.

For example:

class EmailSenderService extends AbstractNotificationService {
  static identifier = "email-sender"
  // ...
}

---

constructor

You can use the constructor of your notification provider to access the different services in Medusa through dependency injection.

You can also use the constructor to initialize your integration with the third-party provider. For example, if you use a client to connect to the third-party provider’s APIs, you can initialize it in the constructor and use it in other methods in the service.

Additionally, if you’re creating your notification provider as an external plugin to be installed on any Medusa backend and you want to access the options added for the plugin, you can access it in the constructor.

Example

// ...
import { AbstractNotificationService, OrderService } from "@medusajs/medusa"
import { EntityManager } from "typeorm"

class EmailSenderService extends AbstractNotificationService {
  // ...
  protected orderService: OrderService

  constructor(container, options) {
    super(container)
    // you can access options here in case you're
    // using a plugin

    this.orderService = container.orderService

    // you can also initialize a client that
    // communicates with a third-party service.
    this.client = new Client(options)
  }

  // ...
}

export default EmailSenderService

Parameters

containerRecord<string, unknown>Required

An instance of MedusaContainer that allows you to access other resources, such as services, in your Medusa backend.

configRecord<string, unknown>

If this notification provider is created in a plugin, the plugin's options are passed in this parameter.

---

Properties

identifierstringRequired

containerRecord<string, unknown>Required

An instance of MedusaContainer that allows you to access other resources, such as services, in your Medusa backend.

manager_EntityManagerRequired

transactionManager_undefined | EntityManagerRequired

__container__anyRequired

configRecord<string, unknown>

If this notification provider is created in a plugin, the plugin's options are passed in this parameter.

__configModule__Record<string, unknown>

__moduleDeclaration__Record<string, unknown>

---

Accessors

activeManager_

Returns

EntityManagerEntityManagerRequired

---

Methods

sendNotification

When an event is triggered that your Notification Provider is registered as a handler for, the NotificationService in the Medusa backend executes this method of your Notification Provider.

In this method, you can perform the necessary operation to send the Notification. For example, you can send an email to the customer when they place an order.

Example

class EmailSenderService extends AbstractNotificationService {
  // ...
  async sendNotification(
    event: string,
    data: any,
    attachmentGenerator: unknown
  ): Promise<{
      to: string;
      status: string;
      data: Record<string, unknown>;
    }> {
    if (event === "order.placed") {
      // retrieve order
      const order = await this.orderService.retrieve(data.id)
      // TODO send email

      console.log("Notification sent")
      return {
        to: order.email,
        status: "done",
        data: {
          // any data necessary to send the email
          // for example:
          subject: "You placed a new order!",
          items: order.items,
        },
      }
    }
  }
  // ...
}

Parameters

eventstringRequired

The name of the event that was triggered. For example, order.placed.

dataunknownRequired

The data payload of the event that was triggered. For example, if the order.placed event is triggered, the eventData object contains the property id which is the ID of the order that was placed. You can refer to the Events reference for information on all events and their payloads.

attachmentGeneratorunknownRequired

If you’ve previously register an attachment generator to the NotificationService using the registerAttachmentGenerator method, you have access to it here. You can use the attachmentGenerator to generate on-demand invoices or other documents. The default value of this parameter is null.

Returns

PromisePromise<ReturnedData>Required

The sending details.

resendNotification

This method is used to resend notifications, which is typically triggered by the Resend Notification API Route.

Example

class EmailSenderService extends AbstractNotificationService {
  // ...
  async resendNotification(
    notification: any,
    config: any,
    attachmentGenerator: unknown
  ): Promise<{
      to: string;
      status: string;
      data: Record<string, unknown>;
    }> {
    // check if the receiver should be changed
    const to: string = config.to || notification.to

    // TODO resend the notification using the same data
    // that is saved under notification.data

    console.log("Notification resent")
    return {
      to,
      status: "done",
      data: notification.data, // make changes to the data
    }
  }
}

Parameters

notificationunknownRequired

The original Notification record that was created after you sent the notification with sendNotification. It includes the to and data attributes which are populated originally using the to and data properties of the object you return in sendNotification.

configunknownRequired

The new configuration used to resend the notification. The Resend Notification API Route, allows you to pass a new to field. If specified, it will be available in this config object.

attachmentGeneratorunknownRequired

f you’ve previously register an attachment generator to the NotificationService using the registerAttachmentGenerator method, you have access to it here. You can use the attachmentGenerator to generate on-demand invoices or other documents. The default value of this parameter is null.

Returns

PromisePromise<ReturnedData>Required

The resend details.

withTransaction

Parameters

transactionManagerEntityManager

Returns

thisthisRequired

shouldRetryTransaction_

Parameters

errRecord<string, unknown> | objectRequired

Returns

booleanbooleanRequired

atomicPhase_

Wraps some work within a transactional block. If the service already has a transaction manager attached this will be reused, otherwise a new transaction manager is created.

Type Parameters

TResultobjectRequired

TErrorobjectRequired

Parameters

work(transactionManager: EntityManager) => Promise<TResult>Required

the transactional work to be done

isolationOrErrorHandlerIsolationLevel | (error: TError) => Promise<void | TResult>

the isolation level to be used for the work.

maybeErrorHandlerOrDontFail(error: TError) => Promise<void | TResult>

Potential error handler

Returns

PromisePromise<TResult>Required

the result of the transactional work