docs: documentation for v1.18 (#5652)

* docs: documentation for v.17.5

* fix links

* updated version number

www/apps/docs/content/development/entities/repositories.md

@@ -135,9 +135,9 @@ export const GET = async (
 
 You can learn more about API Route [here](../api-routes/overview.mdx).
 
-### Services and Subscribers
+### Services
 
-As custom repositories are registered in the [dependency container](../fundamentals/dependency-injection.md#dependency-container-and-injection), they can be accessed through dependency injection in the constructor of a service or a subscriber.
+As custom repositories are registered in the [dependency container](../fundamentals/dependency-injection.md#dependency-container-and-injection), they can be accessed through dependency injection in the constructor of a service.
 
 For example:
 
@@ -167,6 +167,32 @@ class PostService extends TransactionBaseService {
 
 You can learn more about services [here](../services/overview.mdx).
 
+### Subscribers
+
+A subscriber handler function can resolve a repository using the `container` property of its parameter. The `container` has a method `resolve` which accepts the registration name of the repository as a parameter.
+
+For example:
+
+```ts title=src/subscribers/post-handler.ts
+import {
+  type SubscriberArgs,
+} from "@medusajs/medusa"
+
+import { PostRepository } from "../repositories/post"
+
+export default async function postHandler({ 
+  data, eventName, container, pluginOptions, 
+}: SubscriberArgs) {
+  const postRepository: PostRepository = container.resolve(
+    "postRepository"
+  )
+
+  // ...
+}
+
+// ...
+```
+
 ### Other Resources
 
 Resources that have access to the dependency container can access repositories just like any other resources. You can learn more about the dependency container and dependency injection in [this documentation](../fundamentals/dependency-injection.md).

www/apps/docs/content/development/events/create-module.md

@@ -62,9 +62,9 @@ In the class you must implement the `emit` method. You can optionally implement
 
 ### Note About the eventToSubscribersMap Property
 
-The `AbstractEventBusModuleService` implements two methods for handling subscription: `subscribe` and `unsubscribe`. In these methods, the subscribed handler methods are managed within a class property `eventToSubscribersMap`, which is a JavaScript Map. The map's keys are the event names, whereas the value of each key is an array of subscribed handler methods.
+The `AbstractEventBusModuleService` implements two methods for handling subscription: `subscribe` and `unsubscribe`. In these methods, the subscribed handler functions are managed within a class property `eventToSubscribersMap`, which is a JavaScript Map. The map's keys are the event names, whereas the value of each key is an array of subscribed handler functions.
 
-In your custom implementation, you can use this property to manage the subscribed handler methods. For example, you can get the subscribers of a method using the `get` method of the map:
+In your custom implementation, you can use this property to manage the subscribed handler functions. For example, you can get the subscribers of a method using the `get` method of the map:
 
 ```ts
 const eventSubscribers = 
@@ -144,13 +144,13 @@ class CustomEventBus extends AbstractEventBusModuleService {
 
 As mentioned earlier, this method is already implemented in the `AbstractEventBusModuleService` class. This section explains how you can implement your custom subscribe logic if necessary.
 
-The `subscribe` method attaches a handler method to the specified event, which is run when the event is triggered. It is typically used inside a subscriber class.
+The `subscribe` method attaches a handler function to the specified event, which is run when the event is triggered. It is typically used inside a subscriber class.
 
 The  `subscribe` method accepts three parameters:
 
-1. The first parameter `eventName` is a required string. It indicates which event the handler method is subscribing to.
+1. The first parameter `eventName` is a required string. It indicates which event the handler function is subscribing to.
 2. The second parameter `subscriber` is a required function that performs an action when the event is triggered.
-3. The third parameter `context` is an optional object that has the property `subscriberId`. Subscriber IDs are useful to differentiate between handler methods when retrying a failed method. It’s also useful for unsubscribing an event handler. Note that if you must implement the mechanism around assigning IDs to subscribers when you override the `subscribe` method.
+3. The third parameter `context` is an optional object that has the property `subscriberId`. Subscriber IDs are useful to differentiate between handler functions when retrying a failed method. It’s also useful for unsubscribing an event handler. Note that if you must implement the mechanism around assigning IDs to subscribers when you override the `subscribe` method.
 
 The implementation of this method depends on the service you’re using for the event bus:
 
@@ -170,11 +170,11 @@ class CustomEventBus extends AbstractEventBusModuleService {
 
 As mentioned earlier, this method is already implemented in the `AbstractEventBusModuleService` class. This section explains how you can implement your custom unsubscribe logic if necessary.
 
-The `unsubscribe` method is used to unsubscribe a handler method from an event.
+The `unsubscribe` method is used to unsubscribe a handler function from an event.
 
 The `unsubscribe` method accepts three parameters:
 
-1. The first parameter `eventName` is a required string. It indicates which event the handler method is unsubscribing from.
+1. The first parameter `eventName` is a required string. It indicates which event the handler function is unsubscribing from.
 2. The second parameter `subscriber` is a required function that was initially subscribed to the event.
 3. The third parameter `context` is an optional object that has the property `subscriberId`. It can be used to specify the ID of the subscriber to unsubscribe.
 

www/apps/docs/content/development/events/create-subscriber-deprecated.md

@@ -0,0 +1,140 @@
+---
+description: 'Learn how to create a subscriber in Medusa. You can use subscribers to implement functionalities like sending an order confirmation email.'
+addHowToData: true
+---
+
+# (Deprecated) How to Create a Subscriber
+
+In this document, you’ll learn how to create a [Subscriber](./subscribers.mdx) in Medusa that listens to events to perform an action.
+
+:::note
+
+Following v1.18 of `@medusajs/medusa`, the approach in this guide is deprecated. It's recommended to follow [this guide](./create-subscriber.md) instead.
+
+:::
+
+## Implementation
+
+A subscriber is a TypeScript or JavaScript file that is created under `src/subscribers`. Its file name, by convention, should be the class name of the subscriber without the word `Subscriber`. For example, if the subscriber is `HelloSubscriber`, the file name should be `hello.ts`.
+
+After creating the file under `src/subscribers`, in the constructor of your subscriber, listen to events using `eventBusService.subscribe` , where `eventBusService` is a service injected into your subscriber’s constructor.
+
+The `eventBusService.subscribe` method receives the name of the event as a first parameter and as a second parameter a method in your subscriber that will handle this event.
+
+For example, here is the `OrderNotifierSubscriber` class created in `src/subscribers/order-notifier.ts`:
+
+```ts title=src/subscribers/order-notifier.ts
+class OrderNotifierSubscriber {
+  constructor({ eventBusService }) {
+    eventBusService.subscribe("order.placed", this.handleOrder)
+  }
+
+  handleOrder = async (data) => {
+    console.log("New Order: " + data.id)
+  }
+}
+
+export default OrderNotifierSubscriber
+```
+
+This subscriber registers the method `handleOrder` as one of the handlers of the `order.placed` event. The method `handleOrder` will be executed every time an order is placed. It receives the order ID in the `data` parameter. You can then use the order’s details to perform any kind of task you need.
+
+:::tip
+
+For the `order.placed` event, the `data` object won't contain other order data. Only the ID of the order. You can retrieve the order information using the `orderService`.
+
+:::
+
+### Subscriber ID
+
+The `subscribe` method of the `eventBusService` accepts a third optional parameter which is a context object. This object has a property `subscriberId` with its value being a string. This ID is useful when there is more than one handler method attached to a single event or if you have multiple Medusa backends running. This allows the events bus service to differentiate between handler methods when retrying a failed one.
+If a subscriber ID is not passed on subscription, all handler methods are run again. This can lead to data inconsistencies or general unwanted behavior in your system. On the other hand, if you want all handler methods to run again when one of them fails, you can omit passing a subscriber ID.
+
+An example of using the subscribe method with the third parameter:
+
+```ts
+eventBusService.subscribe("order.placed", this.handleOrder, {
+  subscriberId: "my-unique-subscriber",
+})
+```
+
+---
+
+## Retrieve Medusa Configurations
+
+Within your subscriber, you may need to access the Medusa configuration exported from `medusa-config.js`. To do that, you can access `configModule` using dependency injection.
+
+For example:
+
+```ts
+import { ConfigModule, EventBusService } from "@medusajs/medusa"
+
+type InjectedDependencies = {
+  eventBusService: EventBusService
+  configModule: ConfigModule
+}
+
+class OrderNotifierSubscriber {
+  protected readonly configModule_: ConfigModule
+
+  constructor({
+    eventBusService,
+    configModule,
+  }: InjectedDependencies) {
+    this.configModule_ = configModule
+    eventBusService.subscribe("order.placed", this.handleOrder)
+  }
+
+  // ...
+}
+
+export default OrderNotifierSubscriber
+```
+
+---
+
+## Using Services in Subscribers
+
+You can access any service through the dependencies injected to your subscriber’s constructor.
+
+For example:
+
+```ts title=src/subscribers/order-notifier.ts
+class OrderNotifierSubscriber {
+  constructor({ productService, eventBusService }) {
+      this.productService = productService
+
+      eventBusService.subscribe(
+        "order.placed", 
+        this.handleOrder
+      )
+  }
+  // ...
+}
+```
+
+You can then use `this.productService` anywhere in your subscriber’s methods. For example:
+
+```ts title=src/subscribers/order-notifier.ts
+class OrderNotifierSubscriber {
+  // ...
+  handleOrder = async (data) => {
+    // ...
+    const product = this.productService.list()
+  }
+}
+```
+
+:::note
+
+When using attributes defined in the subscriber, such as the `productService` in the example above, you must use an arrow function to declare the method. Otherwise, the attribute will be undefined when used.
+
+:::
+
+---
+
+## See Also
+
+- [Example: send order confirmation email](../../modules/orders/backend/send-order-confirmation.md)
+- [Example: send registration confirmation email](../../modules/customers/backend/send-confirmation.md)
+- [Create a Plugin](../plugins/create.mdx)