docs: describes usage of plugin

packages/medusa-plugin-restock-notification/src/api/routes/add-email.js

@@ -18,7 +18,7 @@ export default async (req, res) => {
       "restockNotificationService"
     )
     await restockNotificationService.addEmail(variant_id, value.email)
-    res.sendStatus(200)
+    res.sendStatus(201)
   } catch (err) {
     res.status(400).json({ message: err.message })
   }

packages/medusa-plugin-restock-notification/src/models/restock-notification.ts

@@ -30,3 +30,25 @@ export class RestockNotification {
   @UpdateDateColumn({ type: "timestamptz" })
   updated_at: Date
 }
+
+/**
+ * @schema restock_notification
+ * title: "Restock Notification"
+ * description: "Holds a list of emails that wish to be notifed when an item is restocked."
+ * x-resourceId: restock_notification
+ * properties:
+ *   variant_id:
+ *     type: string
+ *     description: "The id of the variant that customers have signed up to be notified about,"
+ *   emails:
+ *     type: string[]
+ *     description: "The emails of customers who wish to be notified about restocks."
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     description: "The date time at which the first restock signup was made."
+ *   updated_at:
+ *     type: string
+ *     format: date-time
+ *     description: "The date time at which the first last signup was made."
+ */

packages/medusa-plugin-restock-notification/src/services/__tests__/restock-notification.js

@@ -88,10 +88,7 @@ describe("RestockNotificationService", () => {
     it("successfully adds email to non-existing noti", async () => {
       jest.clearAllMocks()
 
-      const result = await restockNotiService.addEmail(
-        "variant_test",
-        "seb@med-test.com"
-      )
+      await restockNotiService.addEmail("variant_test", "seb@med-test.com")
 
       expect(RestockNotificationModel.create).toHaveBeenCalledTimes(1)
       expect(RestockNotificationModel.create).toHaveBeenCalledWith({
@@ -105,10 +102,7 @@ describe("RestockNotificationService", () => {
     it("successfully adds email to existing noti", async () => {
       jest.clearAllMocks()
 
-      const result = await restockNotiService.addEmail(
-        "variant_1234",
-        "seb@med-test.com"
-      )
+      await restockNotiService.addEmail("variant_1234", "seb@med-test.com")
 
       expect(RestockNotificationModel.save).toHaveBeenCalledTimes(1)
       expect(RestockNotificationModel.save).toHaveBeenCalledWith({

packages/medusa-plugin-restock-notification/src/services/restock-notification.js

@@ -1,6 +1,11 @@
 import { MedusaError } from "medusa-core-utils"
 import { BaseService } from "medusa-interfaces"
 
+/**
+ * Restock notifications can be used to keep track of customers who wish to be
+ * notified when a certain item is restocked. Restock notifications can only
+ * apply to sold out items and will be deleted once items are restocked.
+ */
 class RestockNotificationService extends BaseService {
   constructor(
     {
@@ -41,6 +46,12 @@ class RestockNotificationService extends BaseService {
     return cloned
   }
 
+  /**
+   * Retrieves a restock notification by a given variant id.
+   * @param {string} variantId - the variant id to retrieve restock notification
+   *  for
+   * @return {Promise<RestockNotification>} The restock notification
+   */
   async retrieve(variantId) {
     const restockRepo = this.manager_.getRepository(
       this.restockNotificationModel_
@@ -48,6 +59,13 @@ class RestockNotificationService extends BaseService {
     return await restockRepo.findOne({ where: { variant_id: variantId } })
   }
 
+  /**
+   * Adds an email to be notified when a certain variant is restocked. Throws if
+   * the variant is not sold out.
+   * @param {string} variantId - the variant id to sign up for notifications for
+   * @param {string} email - the email to signup
+   * @return {Promise<RestockNotification>} The resulting restock notification
+   */
   async addEmail(variantId, email) {
     return this.atomicPhase_(async (manager) => {
       const restockRepo = manager.getRepository(this.restockNotificationModel_)
@@ -81,6 +99,13 @@ class RestockNotificationService extends BaseService {
     })
   }
 
+  /**
+   * Checks if anyone has signed up for restock notifications on a given variant
+   * and emits a restocked event to the event bus. After successful emission the
+   * restock notification is deleted.
+   * @param {string} variantId - the variant id to trigger restock for
+   * @return {Promise<RestockNotification>} The resulting restock notification
+   */
   async triggerRestock(variantId) {
     return this.atomicPhase_(async (manager) => {
       const restockRepo = manager.getRepository(this.restockNotificationModel_)