api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,5 @@
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
|
||||
# Notifications Plugins
|
||||
|
||||
<DocCardList />
|
||||
@@ -0,0 +1,209 @@
|
||||
---
|
||||
description: 'Learn how to integrate Mailchimp with the Medusa backend. Learn how to install the plugin on the Medusa backend and how to add a subscription form.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Mailchimp
|
||||
|
||||
In this document, you’ll learn about the Mailchimp plugin, what it does, and how to use it.
|
||||
|
||||
## Overview
|
||||
|
||||
[Mailchimp](https://mailchimp.com) is an email marketing service that can be used to create newsletters and subscriptions.
|
||||
|
||||
By integrating Mailchimp with Medusa, customers will be able to subscribe from Medusa to your Mailchimp newsletter and will be automatically added to your Mailchimp subscribers list.
|
||||
|
||||
:::note
|
||||
|
||||
This plugin is only used to allow your customers to subscribe but does not actually do any email sending. If you want to send emails to customers based on specific events, for example, when an order is placed, you should check out the [SendGrid plugin](./sendgrid.mdx) instead.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before going further with this guide make sure you have a Medusa backend set up. You can follow the [Quickstart guide](../../development/backend/install.mdx).
|
||||
|
||||
You also need a Mailchimp account, so please [create one](https://mailchimp.com/signup) before you start.
|
||||
|
||||
---
|
||||
|
||||
## Obtain Mailchimp Keys
|
||||
|
||||
To integrate the plugin into Medusa you need two keys: The API Key and the Newsletter list or Audience ID. The API Key acts as a credential for your account, whereas the Newsletter list ID determines which audience should the subscribed customers be added to.
|
||||
|
||||
You can follow [this guide](https://mailchimp.com/help/about-api-keys/#Find_or_generate_your_API_key) from Mailchimp’s documentation to obtain an API Key.
|
||||
|
||||
You can follow [this guide](https://mailchimp.com/help/find-audience-id/) from Mailchimp’s documentation to obtain your Newsletter list or Audience ID.
|
||||
|
||||
---
|
||||
|
||||
## Install the Plugin
|
||||
|
||||
In the directory of your Medusa backend, run the following command to install the Mailchimp plugin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-plugin-mailchimp
|
||||
```
|
||||
|
||||
### Add Keys
|
||||
|
||||
Open `.env` and add the following keys:
|
||||
|
||||
```bash
|
||||
MAILCHIMP_API_KEY=<YOUR_API_KEY>
|
||||
MAILCHIMP_NEWSLETTER_LIST_ID=<YOUR_NEWSLETTER_LIST_ID>
|
||||
```
|
||||
|
||||
Make sure to replace `<YOUR_API_KEY>` with your API Key and `<YOUR_NEWSLETTER_LIST_ID>` with your Newsletter list or Audience ID.
|
||||
|
||||
### Add Plugin to Medusa Config
|
||||
|
||||
Open `medusa-config.js` and add the new plugin into the `plugins` array:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...,
|
||||
{
|
||||
resolve: `medusa-plugin-mailchimp`,
|
||||
options: {
|
||||
api_key: process.env.MAILCHIMP_API_KEY,
|
||||
newsletter_list_id:
|
||||
process.env.MAILCHIMP_NEWSLETTER_LIST_ID,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test it Out
|
||||
|
||||
This plugin adds new `POST` and `PUT` endpoints at `/mailchimp/subscribe`. These endpoints require in the body of the request an `email` field. You can also optionally include a `data` object that holds any additional data you want to send to Mailchimp. You can check out [Mailchimp’s subscription documentation](https://mailchimp.com/developer/marketing/api/list-merges/) for more details on the data you can send.
|
||||
|
||||
### Without Additional Data
|
||||
|
||||
Try sending a `POST` or `PUT` request to `/mailchimp/subscribe` with the following JSON body:
|
||||
|
||||
```json noReport
|
||||
{
|
||||
"email": "example@gmail.com"
|
||||
}
|
||||
```
|
||||
|
||||
If the subscription is successful, a `200` response code will be returned with `OK` message. If the same email address is used again in the `POST`, a `400` response will be returned with an error page. If this can occur in your usecase, use the `PUT` endpoint to prevent this.
|
||||
|
||||
|
||||
|
||||
If you check your Mailchimp dashboard, you should find the email added to your Audience list.
|
||||
|
||||
|
||||
|
||||
### With Additional Data
|
||||
|
||||
Here’s an example of sending additional data with the subscription:
|
||||
|
||||
```json noReport
|
||||
{
|
||||
"email": "example@gmail.com",
|
||||
"data": {
|
||||
"tags": ["customer"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
All fields inside `data` will be sent to Mailchimp’s API along with the email.
|
||||
|
||||
---
|
||||
|
||||
## Use Mailchimp Service
|
||||
|
||||
If you want to subscribe to users without using this endpoint or at a specific place in your code, you can use Mailchimp’s service `mailchimpService` in your endpoints, services, or subscribers. This service has a method `subscribeNewsletter` which lets you use the subscribe functionality.
|
||||
|
||||
Here’s an example of using the `mailchimpService` inside an endpoint:
|
||||
|
||||
```jsx title=src/api/index.ts
|
||||
const mailchimpService = req.scope.resolve("mailchimpService")
|
||||
|
||||
mailchimpService.subscribeNewsletter(
|
||||
"example@gmail.com",
|
||||
{ tags: ["customer"] } // optional
|
||||
)
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
You can learn more about how you can use services in your endpoints, services, and subscribers in the [Services documentation](../../development/services/create-service.mdx#using-your-custom-service).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Add Subscription Form
|
||||
|
||||
This section has a simple example of adding a subscription form in your storefront. The code is for React-based frameworks but you can use the same logic for your storefronts regardless of the framework you are using.
|
||||
|
||||
You’ll need to use [axios](https://github.com/axios/axios) to send API requests, so if you don’t have it installed make sure you install it first:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install axios
|
||||
```
|
||||
|
||||
Then, in the component you want to add the subscription form add the following code:
|
||||
|
||||
```tsx
|
||||
import axios from "axios"
|
||||
import { useState } from "react"
|
||||
|
||||
export default function NewsletterForm() {
|
||||
const [email, setEmail] = useState("")
|
||||
|
||||
function subscribe(e) {
|
||||
e.preventDefault()
|
||||
if (!email) {
|
||||
return
|
||||
}
|
||||
|
||||
axios.post("http://localhost:9000/mailchimp/subscribe", {
|
||||
email,
|
||||
})
|
||||
.then((e) => {
|
||||
alert("Subscribed sucessfully!")
|
||||
setEmail("")
|
||||
})
|
||||
.catch((e) => {
|
||||
console.error(e)
|
||||
alert("An error occurred")
|
||||
})
|
||||
}
|
||||
|
||||
return (
|
||||
<form onSubmit={subscribe}>
|
||||
<h2>Sign Up for our newsletter</h2>
|
||||
<input
|
||||
type="email"
|
||||
name="email"
|
||||
id="email"
|
||||
placeholder="example@gmail.com"
|
||||
value={email}
|
||||
onChange={(e) => setEmail(e.target.value)}
|
||||
/>
|
||||
<button type="submit">Subscribe</button>
|
||||
</form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
This will result in a subscription form similar to the following:
|
||||
|
||||
|
||||
|
||||
If you try entering an email and clicking Subscribe, the email will be subscribed to your Mailchimp newsletter successfully.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- Check out [SendGrid plugin](./sendgrid.mdx) for more Email functionalities.
|
||||
- [Plugins Overview](../../development/plugins/overview.mdx)
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,106 @@
|
||||
---
|
||||
description: 'Learn how to integrate Slack with the Medusa backend. Learn how to create and configure a Slack app and install the Slack plugin on the Medusa backend.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Slack
|
||||
|
||||
In this documentation, you'll learn how to add the [Slack plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-slack-notification) to your Medusa backend to start receiving order notifications.
|
||||
|
||||
## Overview
|
||||
|
||||
When you add this plugin, the store owner can receive order notifications into their Slack workspace.
|
||||
|
||||
The notification contains details about the order including:
|
||||
|
||||
- Customer's details and address
|
||||
- Items ordered, their quantity, and the price
|
||||
- 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.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Slack Account
|
||||
|
||||
To follow along with this guide, you need to have a Slack account with a connected workspace. If you don’t have one, you can [create a free account on Slack](https://slack.com/).
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
This tutorial assumes you already have a Medusa backend installed. If you don’t, please follow along with the [quickstart guide](../../development/backend/install.mdx). The Medusa backend must also have an event bus module installed, which is available when using the default Medusa backend starter.
|
||||
|
||||
---
|
||||
|
||||
## Create Slack App
|
||||
|
||||
The first step is to create a Slack app. This app will be connected to your workspace and will have Incoming Webhooks activated to receive notifications from the Medusa backend using a Webhook URL.
|
||||
|
||||
Go to [Slack API](https://api.slack.com/) and click Create app. This will take you to a new page with a pop-up. In the pop-up, choose From scratch.
|
||||
|
||||
|
||||
|
||||
You’ll then need to enter some info like the App name and the workspace it will be connected to. Once you’re done, the app will be created.
|
||||
|
||||
### Activate Incoming Webhooks
|
||||
|
||||
To activate Incoming Webhooks, choose Features > Incoming Webhooks from the sidebar. At first, it will be disabled so make sure to enable it by switching the toggle.
|
||||
|
||||
|
||||
|
||||
### Add New Webhook
|
||||
|
||||
After activating Incoming Webhooks, on the same page scroll down and click on the Add New Webhook to Workspace button.
|
||||
|
||||
|
||||
|
||||
After that, choose the channel to send the notifications to. You can also choose a DM to send the notifications to. Once you’re done click Allow.
|
||||
|
||||
|
||||
|
||||
This will create a new Webhook with a URL which you can see in the table at the end of the Incoming Webhooks page. Copy the URL as you’ll use it in the next section.
|
||||
|
||||
---
|
||||
|
||||
## Install Slack Plugin
|
||||
|
||||
The next step is to install Medusa’s [Slack plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-slack-notification) into your Medusa backend.
|
||||
|
||||
Open the terminal in the Medusa backend’s directory and run the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-plugin-slack-notification
|
||||
```
|
||||
|
||||
After that, open `medusa-config.js` and add the new plugin with its configurations in the `plugins` array:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...,
|
||||
{
|
||||
resolve: `medusa-plugin-slack-notification`,
|
||||
options: {
|
||||
show_discount_code: false,
|
||||
slack_url: `<WEBHOOK_URL>`,
|
||||
admin_orders_url: `http://localhost:7001/a/orders`,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
- Make sure to change `<WEBHOOK_URL>` with the Webhook URL you copied after creating the Slack app.
|
||||
- The `show_discount_code` option enables or disables showing the discount code in the notification sent to Slack.
|
||||
- The `admin_orders_url` is the prefix of the URL of the order detail pages on your admin panel. If you’re using Medusa’s Admin locally, it should be `http://localhost:7001/a/orders`. This will result in a URL like `http://localhost:7001/a/orders/order_01FYP7DM7PS43H9VQ1PK59ZR5G`.
|
||||
|
||||
That’s all you need to do to integrate Slack into Medusa!
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- Install [Medusa's Admin](../../admin/quickstart.mdx) for the full order-management experience.
|
||||
- Install the [Next.js Starter Template](../../starters/nextjs-medusa-starter.mdx).
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
description: 'Learn how to integrate Twilio SMS with the Medusa backend. Learn how to install the Twilio SMS plugin and test it out.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Twilio SMS
|
||||
|
||||
In this document, you’ll learn about the Twilio SMS Plugin, what it does, and how to use it in Medusa.
|
||||
|
||||
## Overview
|
||||
|
||||
[Twilio’s SMS API](https://www.twilio.com/sms) can be used to send users SMS messages instantly. It has a lot of additional features such as Whatsapp messaging and conversations.
|
||||
|
||||
By integrating Twilio SMS into Medusa, you’ll have easy access to Twilio’s SMS API to send SMS messages to your users and customers. You can use it to send Order confirmations, verification codes, reset password messages, and more.
|
||||
|
||||
:::note
|
||||
|
||||
This plugin only gives you access to the Twilio SMS API but does not implement sending messages at any given point. You’ll have to add this yourself where you need it. You can look at the [example later in this tutorial](#example-usage-of-the-plugin) to check how you can send an SMS for a new order.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before going further with this guide make sure you have a Medusa backend set up. You can follow the [Quickstart guide](../../development/backend/install.mdx) if you don’t.
|
||||
|
||||
You also must have a [Twilio account created](https://www.twilio.com/sms) so if you don’t already please go ahead and create one.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve Credentials
|
||||
|
||||
For the [Twilio SMS plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-twilio-sms), you need three credentials from your Twilio account: Account SID, Auth Token, and a Twilio phone number to send from. You can find these three from your [Twilio Console’s homepage](https://console.twilio.com).
|
||||
|
||||
---
|
||||
|
||||
## Install Plugin
|
||||
|
||||
In the directory of your Medusa backend, run the following command to install [Twilio SMS plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-twilio-sms):
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-plugin-twilio-sms
|
||||
```
|
||||
|
||||
Then, you’ll need to add your credentials in `.env`:
|
||||
|
||||
```bash
|
||||
TWILIO_SMS_ACCOUNT_SID=<YOUR_ACCOUNT_SID>
|
||||
TWILIO_SMS_AUTH_TOKEN=<YOUR_AUTH_TOKEN>
|
||||
TWILIO_SMS_FROM_NUMBER=<YOUR_TWILIO_NUMBER>
|
||||
```
|
||||
|
||||
Make sure to replace `<YOUR_ACCOUNT_SID>`, `<YOUR_AUTH_TOKEN>`, and `<YOUR_TWILIO_NUMBER>` with the credentials you obtained from your Twilio Console.
|
||||
|
||||
Finally, add the plugin and its options in the `medusa-config.js` file to the `plugins` array:
|
||||
|
||||
```jsx title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: `medusa-plugin-twilio-sms`,
|
||||
options: {
|
||||
account_sid: process.env.TWILIO_SMS_ACCOUNT_SID,
|
||||
auth_token: process.env.TWILIO_SMS_AUTH_TOKEN,
|
||||
from_number: process.env.TWILIO_SMS_FROM_NUMBER,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
:::tip
|
||||
|
||||
For this example to work, you'll need to have an event bus module installed and configured, which should be available by default.
|
||||
|
||||
:::
|
||||
|
||||
Create the file `src/services/sms.js` in your Medusa backend with the following content:
|
||||
|
||||
```jsx title=src/services/sms.js
|
||||
class SmsSubscriber {
|
||||
constructor({
|
||||
twilioSmsService,
|
||||
orderService,
|
||||
eventBusService,
|
||||
}) {
|
||||
this.twilioSmsService_ = twilioSmsService
|
||||
this.orderService = orderService
|
||||
|
||||
eventBusService.subscribe("order.placed", this.sendSMS)
|
||||
}
|
||||
|
||||
sendSMS = async (data) => {
|
||||
const order = await this.orderService.retrieve(data.id, {
|
||||
relations: ["shipping_address"],
|
||||
})
|
||||
|
||||
if (order.shipping_address.phone) {
|
||||
this.twilioSmsService_.sendSms({
|
||||
to: order.shipping_address.phone,
|
||||
body: "We have received your order #" + data.id,
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export default SmsSubscriber
|
||||
```
|
||||
|
||||
In the `constructor`, you resolve the `twilioSmsService` and `orderService` using dependency injection to use it later in the `sendSMS` method.
|
||||
|
||||
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).
|
||||
|
||||
:::
|
||||
|
||||
:::caution
|
||||
|
||||
If you’re on a Twilio trial make sure that the phone number you entered on checkout is a [verified Twilio number on your console](https://console.twilio.com/us1/develop/phone-numbers/manage/verified).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Notifications Overview](../../development/notification/overview.mdx).
|
||||
- Install the [Medusa admin](../../admin/quickstart.mdx) for functionalities like Gift Cards creation, swaps, claims, order return requests, and more.
|
||||
Reference in New Issue
Block a user