asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: documentation for v1.18 (#5652)

Browse Source 
* docs: documentation for v.17.5

* fix links

* updated version number
This commit is contained in:
Shahed Nasser
2023-11-21 08:57:11 +00:00
committed by GitHub
parent adc60e519c
commit 9c7f95c3d5
36 changed files with 1499 additions and 1336 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/docs/content/plugins/analytics/segment.md
+26 -30
View File
@@ -153,43 +153,41 @@ If the data is not appearing on the destination, the issue is related to your co
In some cases, you might want to track more events or custom events. You can do that using the `SegmentService` provided by the Segment Plugin.
For example, you can add the following subscriber to listen to the `customer.created` event and add tracking for every customer created:
For example, you can add the following [subscriber](../../development/events/subscribers.mdx) to listen to the `customer.created` event and add tracking for every customer created:
```jsx title=src/subscribers/customer.ts
class CustomerSubscriber {
constructor({ segmentService, eventBusService }) {
this.segmentService = segmentService
```ts title=src/subscribers/customer.ts
import {
type SubscriberConfig,
type SubscriberArgs,
CustomerService,
} from "@medusajs/medusa"
eventBusService.subscribe(
"customer.created",
this.handleCustomer
)
}
export default async function handleCustomerCreated({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
const segmentService = container.resolve("segmentService")
handleCustomer = async (data) => {
const customerData = data
delete customerData["password_hash"]
const customerData = data
delete customerData["password_hash"]
this.segmentService.track({
event: "Customer Created",
userId: data.id,
properties: customerData,
})
}
this.segmentService.track({
event: "Customer Created",
userId: data.id,
properties: customerData,
})
}
export default CustomerSubscriber
export const config: SubscriberConfig = {
event: CustomerService.Events.CREATED,
context: {
subscriberId: "customer-created-handler",
},
}
```
You resolve the `SegmentService` using dependency injection. Then, when the `customer.created` event is triggered, you use the `track` method available in the `SegmentService` to send tracking data to Segment.
In the handler function, you resolve the `SegmentService` using the `container` of type [MedusaContainer](../../development/fundamentals/dependency-injection.md). Then, you use the `track` method of the `SegmentService` to send tracking data to Segment.
:::info
Services can be resolved and used in Subscribers, API Routes, and other Services. Learn [how to resolve services in the Services documentation](../../development/services/create-service.mdx#using-your-custom-service).
:::
`track` accepts an object of data, where the keys `event` and `userId` are required. Instead of `userId`, you can use `anonymousId` to pass an anonymous user ID.
The `track` method accepts an object of data, where the keys `event` and `userId` are required. Instead of `userId`, you can use `anonymousId` to pass an anonymous user ID.
If you want to pass additional data to Segment, pass them under the `properties` object key.
@@ -199,8 +197,6 @@ The `SegmentService` also provides the method `identify` to tie a user to their
After adding the above subscriber, run your backend again if it isn’t running and create a customer using the REST APIs or one of the Medusa storefronts. If you check the Debugger in your Segment source, you should see a new event “Customer Created” tracked. If you click on it, you’ll see the data you passed to the `track` method.
![The customer created event is recorded on the Segment source](https://res.cloudinary.com/dza7lstvk/image/upload/v1668000759/Medusa%20Docs/Segment/4LD41xE_qungdw.png)
---
## See Also
www/apps/docs/content/plugins/cms/contentful.mdx
+6 -3
View File
@@ -405,8 +405,11 @@ npm install --save-dev contentful-migration
Finally, create a [loader](../../development/loaders/overview.mdx) at `src/loaders/index.ts` with the following content:
```ts title=src/loaders/index.ts
import { ConfigModule, StoreService } from "@medusajs/medusa"
import { AwilixContainer } from "awilix"
import {
ConfigModule,
StoreService,
MedusaContainer,
} from "@medusajs/medusa"
import { runMigration } from "contentful-migration"
import {
productMigration,
@@ -434,7 +437,7 @@ type ContentfulPluginType = {
}
export default async (
container: AwilixContainer,
container: MedusaContainer,
config: ConfigModule
): Promise<void> => {
// ensure that migration only runs once
www/apps/docs/content/plugins/notifications/slack.md
+1 -1
View File
@@ -18,7 +18,7 @@ The notification contains details about the order including:
- Order totals including Tax amount.
- Promotion details if there are any (this is optional and can be turned off).
The plugin registers a subscriber to the `order.placed` event. When an order is placed, the subscriber handler method uses the ID of the order to retrieve order details mentioned above.
The plugin registers a subscriber to the `order.placed` event. When an order is placed, the subscriber handler function uses the ID of the order to retrieve order details mentioned above.
Then, the order notification is sent to Slack using Webhooks. So, you'll need to create a Slack App, add it into your workspace, and activate Incoming Webhooks.
www/apps/docs/content/plugins/notifications/twilio-sms.md
+33 -42
View File
@@ -73,63 +73,56 @@ const plugins = [
## Example Usage of the Plugin
This plugin adds the service `twilioSmsService` to your Medusa backend. To send SMS using it, all you have to do is resolve it in your file as explained in the [Services](../../development/services/create-service.mdx#using-your-custom-service) documentation.
This plugin adds the service `twilioSmsService` to your Medusa backend. To send SMS using it, all you have to do is resolve it in your file as explained in the [dependency injection](../../development/fundamentals/dependency-injection.md) documentation.
In this example, you’ll create a subscriber that listens to the `order.placed` event and sends an SMS to the customer to confirm their order.
In this example, you’ll create a [subscriber](../../development/events/subscribers.mdx) that listens to the `order.placed` event and sends an SMS to the customer to confirm their order.
:::tip
For this example to work, you'll need to have an event bus module installed and configured, which should be available by default.
For this example to work, you'll need to have an [event bus module](../../development/events/index.mdx) installed and configured, which should be available by default.
:::
Create the file `src/services/sms.js` in your Medusa backend with the following content:
Create the file `src/subscriber/sms.ts` in your Medusa backend with the following content:
```js title=src/services/sms.js
class SmsSubscriber {
constructor({
twilioSmsService,
orderService,
eventBusService,
}) {
this.twilioSmsService_ = twilioSmsService
this.orderService = orderService
```ts title=src/subscriber/sms.ts
import {
type SubscriberConfig,
type SubscriberArgs,
OrderService,
} from "@medusajs/medusa"
eventBusService.subscribe("order.placed", this.sendSMS)
}
export default async function handleOrderPlaced({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
const twilioSmsService = container.resolve("twilioSmsService")
const orderService: OrderService = container.resolve(
"orderService"
)
sendSMS = async (data) => {
const order = await this.orderService.retrieve(data.id, {
relations: ["shipping_address"],
const order = await orderService.retrieve(data.id, {
relations: ["shipping_address"],
})
if (order.shipping_address.phone) {
twilioSmsService.sendSms({
to: order.shipping_address.phone,
body: "We have received your order #" + data.id,
})
if (order.shipping_address.phone) {
this.twilioSmsService_.sendSms({
to: order.shipping_address.phone,
body: "We have received your order #" + data.id,
})
}
}
}
export default SmsSubscriber
export const config: SubscriberConfig = {
event: OrderService.Events.PLACED,
context: {
subscriberId: "order-placed-handler",
},
}
```
In the `constructor`, you resolve the `twilioSmsService` and `orderService` using dependency injection to use it later in the `sendSMS` method.
In the handler function, you resolve the `twilioSmsService` and `orderService` using `container` of type [MedusaContainer](../../development/fundamentals/dependency-injection.md). You then retrieve the order's details, and send an SMS to the customer based on the phone number in their shipping address.
You also subscribe to the event `order.placed` and sets the event handler to be `sendSMS`.
In `sendSMS`, you first retrieve the order with its relation to `shipping_address` which contains a `phone` field. If the phone is set, you send an SMS to the customer using the method `sendSms` in the `twilioSmsService`.
This method accepts an object of parameters. These parameters are based on Twilio’s SMS APIs. You can check their [API documentation](https://www.twilio.com/docs/sms/api/message-resource#create-a-message-resource) for more fields that you can add.
If you create an order now on your storefront, you should receive a message from Twilio on the phone number you entered in the shipping address.
:::tip
If you don’t have a storefront set up yet, you can install the [Next.js Starter Template](../../starters/nextjs-medusa-starter.mdx).
:::
The `sendSms` method of the Twilio service accepts an object of parameters. These parameters are based on Twilio’s SMS APIs. You can check their [API documentation](https://www.twilio.com/docs/sms/api/message-resource#create-a-message-resource) for more fields that you can add.
:::caution
@@ -137,8 +130,6 @@ If you’re on a Twilio trial make sure that the phone number you entered on che
:::
![Twilio Dashboard](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001219/Medusa%20Docs/Stripe/MXtQMiL_kb7kxe.png)
---
## See Also
www/apps/docs/content/plugins/other/restock-notifications.md
+32 -47
View File
@@ -28,7 +28,7 @@ Before you follow this guide, you must have a Medusa backend installed. If not,
### Event-Bus Module
To trigger events to the subscribed handler methods, you must have an event-bus module installed. For development purposes, you can use the [Local module](../../development/events/modules/local.md) which should be enabled by default in your Medusa backend.
To trigger events to the subscribed handler functions, you must have an event-bus module installed. For development purposes, you can use the [Local module](../../development/events/modules/local.md) which should be enabled by default in your Medusa backend.
For production, it's recommended to use the [Redis module](../../development/events/modules/redis.md).
@@ -114,64 +114,49 @@ The SendGrid plugin already listens to and handles the `restock-notification.res
:::
Here's an example of a subscriber that listens to the `restock-notification.restocked` event and uses the [SendGrid plugin](../notifications/sendgrid.mdx) to send the subscribed customers an email:
Here's an example of a [subscriber](../../development/events/subscribers.mdx) that listens to the `restock-notification.restocked` event and uses the [SendGrid plugin](../notifications/sendgrid.mdx) to send the subscribed customers an email:
```ts title=src/subscribers/restock-notification.ts
import {
EventBusService,
type SubscriberConfig,
type SubscriberArgs,
ProductVariantService,
} from "@medusajs/medusa"
type InjectedDependencies = {
eventBusService: EventBusService,
sendgridService: any
productVariantService: ProductVariantService
export default async function handleRestockNotification({
data, eventName, container, pluginOptions,
}: SubscriberArgs<Record<string, string>>) {
const sendgridService = container.resolve("sendgridService")
const productVariantService: ProductVariantService =
container.resolve("productVariantService")
// retrieve variant
const variant = await this.productVariantService_.retrieve(
data.variant_id
)
this.sendGridService_.sendEmail({
templateId: "restock-notification",
from: "hello@medusajs.com",
to: data.emails,
dynamic_template_data: {
// any data necessary for your template...
variant,
},
})
}
class RestockNotificationSubscriber {
protected sendGridService_: any
protected productVariantService_: ProductVariantService
constructor({
eventBusService,
sendgridService,
productVariantService,
}: InjectedDependencies) {
this.sendGridService_ = sendgridService
this.productVariantService_ = productVariantService
eventBusService.subscribe(
"restock-notification.restocked",
this.handleRestockNotification
)
}
handleRestockNotification = async ({
variant_id,
emails,
}) => {
// retrieve variant
const variant = await this.productVariantService_.retrieve(
variant_id
)
this.sendGridService_.sendEmail({
templateId: "restock-notification",
from: "hello@medusajs.com",
to: emails,
dynamic_template_data: {
// any data necessary for your template...
variant,
},
})
}
export const config: SubscriberConfig = {
event: "restock-notification.restocked",
context: {
subscriberId: "restock-handler",
},
}
export default RestockNotificationSubscriber
```
Handler methods subscribed to the `restock-notification.restocked` event, which in this case is the `handleRestockNotification` method, receive the following object data payload as a parameter:
The handler function receives in the `data` property of the first parameter the following properties:
- `variant_id`: The ID of the variant that has been restocked.
- `emails`: An array of strings indicating the email addresses subscribed to the restocked variant. Here, you pass it along to the SendGrid plugin directly to send the email to everyone subscribed. If necessary, you can also retrieve the customer of that email using the `CustomerService`'s [retrieveByEmail](../../references/services/classes/CustomerService.mdx#retrievebyemail) method.
In the method, you retrieve the variant by its ID using the `ProductVariantService`, then send the email using the SendGrid plugins' `SendGridService`.
In the handler function, you retrieve the variant by its ID using the `ProductVariantService`, then send the email using the SendGrid plugins' `SendGridService`.