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

fix: merge conflicts with master

Browse Source
This commit is contained in:
olivermrbl
2022-04-27 14:21:03 +02:00
parent 00fd096d25 d162cef4c8
commit d7971ba604
69 changed files with 8240 additions and 3476 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@@ -66,17 +66,17 @@ After these four steps and only a couple of minutes, you now have a complete com
Write-ups for all features will be made available in [Github discussions](https://github.com/medusajs/medusa/discussions) prior to starting the implementation process.
### Q1
### H1 2022
- [x] Admin revamp
- [x] Tax API
- [x] Strategy pattern
- [ ] Promotions API
- [x] Tax Calculation Strategy
- [x] Cart Calculation Strategy
- [x] Customer Groups API
- [x] Promotions API
- [x] Price Lists API
- [x] Price Selection Strategy
- [ ] Bulk import / export
### Q2
- [ ] Extended Product API (custom fields, price lists, publishing control, and more)
- [ ] Extended Product API (custom fields, publishing control, and more)
- [ ] Extended Order API (managing placed orders, improved inventory control, and more)
- [ ] Sales Channel API
- [ ] Multi-warehouse support

2
docs/api/store-spec3.json
View File

@@ -1512,7 +1512,7 @@
"/store/carts/{id}": {
"post": {
"operationId": "PostCartsCartPaymentMethodUpdate",
"summary": "Update a Cart\"",
"summary": "Update a Cart",
"description": "Updates a Cart.",
"parameters": [
{

6
docs/content/add-plugins/algolia.md
View File

@@ -14,11 +14,7 @@ Create an account on Algolia and grab your Application ID and Admin API Key from
In your Medusa project, install the plugin using your favourite package manager:
```jsx
yarn add medusa-plugin-algolia@canary
// or
```bash npm2yarn
npm install medusa-plugin-algolia@canary
```

46
docs/content/add-plugins/contentful.md
View File

@@ -36,18 +36,21 @@ For a full guide to how to set up your development environment for Medusa please
In order to get you started with your Gatsby, Contentful, Medusa store you must complete a couple of installations:
- Install the Medusa CLI
```bash npm2yarn
npm install @medusajs/medusa-cli -g
```
yarn global add @medusajs/medusa-cli
npm install -g @medusajs/medusa-cli
```
- Install the Gatsby CLI
```bash npm2yarn
npm install gatsby-cli -g
```
yarn global add gatsby-cli
npm install -g gatsby-cli
```
- [Create a Contentful account](https://www.contentful.com/sign-up/)
- [Install Redis](https://redis.io/topics/quickstart)
```
```bash
brew install redis
brew services start redis
```
@@ -144,7 +147,14 @@ In the `/src` directory there are 4 special subdirectories that are added for yo
#### `/data`
We will be using two seed scripts to kickstart your development, namely `yarn seed:contentful` and `yarn seed`. Data for these seed scripts are contained in the `/data` directory.
We will be using two seed scripts to kickstart your development, namely:
```bash npm2yarn
npm run seed:contentful
npm run seed
```
Data for these seed scripts are contained in the `/data` directory.
When the seed scripts have been executed you will have a Contentful space that holds all the data for your website; this includes content for Pages, Navigtion Menu, etc.
@@ -227,8 +237,8 @@ Now that we have collected your credentials we are ready to migrate the Contentf
You can now run:
```shell
yarn migrate:contentful
```bash npm2yarn
npm run migrate:contentful
```
This script will run each of the migrations in the `contentful-migrations` directory. After it has completed navigate to your Contentful space and click "Content model" in the top navigation bar. You will see that the content types will be imported into your space. Feel free to familiarize yourself with the different types by clicking them and inspecting the different fields that they hold.
@@ -237,8 +247,8 @@ This script will run each of the migrations in the `contentful-migrations` direc
The next step is to seed the Contentful space with some data that can be used to display your ecommerce store's pages and navigation. To seed the database open up your command line and run:
```shell
yarn seed:contentful
```bash npm2yarn
npm run seed:contentful
```
In your Contentful space navigate to "Content" and you will be able to see the different entries in your space. You can filter the entries by type to, for example, only view Pages:
@@ -249,9 +259,9 @@ You will notice that there are not any Products in your store yet and this is be
To do this open your command line and run:
```shell
yarn seed
yarn start
```bash npm2yarn
npm run seed
npm run start
```
This will seed your Medusa database, which will result in `medusa-plugin-contentful` synchronizing data to your Contentful space. Everytime you add or update a product the data will be copied into your Contentful space for further enrichment.
@@ -287,7 +297,11 @@ Once `gatsby new` is complete you should rename the `.env.template` file to `.en
To get your token go to **Settings** > **API Keys** > **Add API key**. Now click save and copy the token specified in the field "Content Delivery API - access token".
After you have copied the token and your space ID to your `.env`, you can run `yarn start` which will start your Gatsby development server on port 8000.
After you have copied the token and your space ID to your `.env`, you can start your Gatsby development server on port 8000 by running:
```bash npm2yarn
npm run start
```
You can now go to https://localhost:8000 to check out your new Medusa store.

183
docs/content/add-plugins/mailchimp.md Normal file
View File

@@ -0,0 +1,183 @@
# 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 our [SendGrid plugin](./sendgrid.mdx) instead.
:::
## Prerequisites
Before going further with this guide make sure you have a Medusa server set up. You can follow our [Quickstart guide](https://docs.medusajs.com/quickstart/quick-start).
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 2 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 server, 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
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 a new `POST` endpoint at `/mailchimp/subscribe`. This endpoint requires 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-members/add-member-to-list/) for more details on the data you can send.
### Without Additional Data
Try sending a `POST` request to `/mailchimp/subscribe` with the following JSON body:
```json
{
"email": "example@gmail.com"
}
```
If the subscription is successful, a `200` response code will be returned with `OK` message.
![Postman](https://i.imgur.com/tpr7uCF.png)
If you check your Mailchimp dashboard, you should find the email added to your Audience list.
![Email Added](https://i.imgur.com/ALz6WUq.png)
### With Additional Data
Here’s an example of sending additional data with the subscription:
```json
{
"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
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](https://docs.medusajs.com/advanced/backend/services/create-service#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://www.google.com/search?client=safari&rls=en&q=axios+github&ie=UTF-8&oe=UTF-8) 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:
```jsx
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:
![Subscription Form](https://i.imgur.com/JHIFEwe.png)
If you try entering an email and clicking Subscribe, the email will be subscribed to your Mailchimp newsletter successfully.
## What’s Next 🚀
- Check out SendGrid plugin for more Email functionalities.
- [Learn more about plugins.](https://docs.medusajs.com/guides/plugins)

11
docs/content/add-plugins/meilisearch.md
View File

@@ -26,11 +26,7 @@ For other installation alternatives, you can head over to Meilisearch's [install
In order to add the plugin to your medusa project, you will need to first install the plugin using your favorite package manager:
```bash
# yarn
yarn add medusa-plugin-meilisearch
# npm
```bash npm2yarn
npm install medusa-plugin-meilisearch
```
@@ -83,11 +79,8 @@ The Medusa + MeiliSearch integration opens up a lot of capabilities for creating
In order to leverage this functionality, you'll need to install the corresponding packages by running:
```bash
# npm
```bash npm2yarn
npm install react-instantsearch-dom @meilisearch/instant-meilisearch
# yarn
yarn add react-instantsearch-dom @meilisearch/instant-meilisearch
```
You can then use the MeiliSearch client in your react app:

4
docs/content/add-plugins/minio.md
View File

@@ -26,8 +26,8 @@ Navigate to users and perform the following steps:
First, install the plugin using your preferred package manager:
```
yarn add medusa-file-minio
```bash npm2yarn
npm install medusa-file-minio
```
Then configure your `medusa-config.js` to include the plugin alongside the required options:

4
docs/content/add-plugins/s3.md
View File

@@ -51,8 +51,8 @@ Upon successfull creation of the user, you are presented with an **Access key ID
First, install the plugin using your preferred package manager:
```
yarn add medusa-file-s3
```bash npm2yarn
npm install medusa-file-s3
```
Then configure your `medusa-config.js` to include the plugin alongside the required options:

4
docs/content/add-plugins/segment.md
View File

@@ -25,8 +25,8 @@ Common integration use cases that can be implemented with Segment include:
Plugins in Medusa's ecosystem come as separate npm packages, that can be installed from the npm registry.
```bash
yarn add medusa-plugin-segment
```bash npm2yarn
npm install medusa-plugin-segment
```
After installation open `medusa-config.js` to configure the Segment plugin, by adding it to your project's plugin array and providing the options required by the plugin, namely the write key obtained from the Segment dashboard.

9
docs/content/add-plugins/sendgrid.md
View File

@@ -1,9 +0,0 @@
# SendGrid (Documentation coming soon)
[View plugin here](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-sendgrid)
<div>
<video width="100%" height="100%" playsinline autoplay muted controls>
<source src="https://user-images.githubusercontent.com/59018053/154807282-1e72671f-1936-411d-b914-e05c6597693a.mp4" type="video/mp4" />
</video>
</div>

3967
docs/content/add-plugins/sendgrid.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

102
docs/content/add-plugins/slack.md
View File

@@ -1,3 +1,101 @@
# Slack (Documentation coming soon)
# Slack
[View plugin here](https://github.com/medusajs/medusa/tree/master/packages/medusa-plugin-slack-notification)
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 server 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 notificaiton 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 Server
This tutorial assumes you already have a Medusa server installed. If you don’t, please follow along with the [quickstart guide](../quickstart/quick-start.md).
### Redis
Medusa's event system works by pushing data into a queue that is based on [Redis](https://redis.io/). This queue then notifies handlers of different events of this data that is pushed into the queue. The handlers then use this data to perform a certain action.
As the Slack plugin will listen to the `order.placed` event to know when to send notifications, you'll need to have Redis installed and configured with your Medusa server.
You can read the [Set up your development enviornment guideline](https://docs.medusajs.com/tutorial/set-up-your-development-environment) to learn more about how you can install and setup Redis.
## 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 server 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.
![Create Slack App](https://i.imgur.com/liVfwF8.png)
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.
![Incoming Webhooks](https://i.imgur.com/5Y0nv4p.png)
### Add New Webhook
After activating Incoming Webhooks, on the same page scroll down and click on the Add New Webhook to Workspace button.
![Add New Webhook](https://i.imgur.com/sejdIqH.png)
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.
![Choose channel or DM](https://i.imgur.com/Zw3f5uF.png)
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 server.
Open the terminal in the Medusa server’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
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!
## What's Next :rocket:
- Install [Medusa's Admin](https://github.com/medusajs/admin) for the full order-management experience.
- Add a Storefront to your Medusa server using [the Next.js starter](https://docs.medusajs.com/starters/nextjs-medusa-starter) or [the Gatsby starter](https://docs.medusajs.com/starters/gatsby-medusa-starter).

4
docs/content/add-plugins/spaces.md
View File

@@ -26,8 +26,8 @@ Navigate to API in the left sidebar. Generate a new Spaces access key. This shou
First, install the plugin using your preferred package manager:
```
yarn add medusa-file-spaces
```bash npm2yarn
npm install medusa-file-spaces
```
Then configure your `medusa-config.js` to include the plugin alongside the required options:

44
docs/content/add-plugins/strapi.md
View File

@@ -28,26 +28,27 @@ First, create a Medusa project using your favorite package manager. You can go a
`npx create-medusa-app` will allow you to create a Medusa store engine, a storefront, and Medusa admin in a single command
```bash
# using npx
npx create-medusa-app
```
# using yarn
Alternatively, using Yarn:
```bash
yarn create medusa-app
```
> When choosing `npx` you are shown different store engine options as part of the setup. For this Strapi tutorial, you should choose `medusa-starter-default`. Optionally, pick a storefront.
**Use `medusa-cli`**
`@medusajs/medusa-cli` is our Command Line Tool for creating the Medusa store engine (alongside many other powerful commands). Use it as such:
`@medusajs/medusa-cli` is our Command Line Tool for creating the Medusa store engine (alongside many other powerful commands). First, install it:
```bash npm2yarn
npm install @medusajs/medusa-cli -g
```
Then, initialize a Medusa project:
```bash
# using yarn
yarn global add @medusajs/medusa-cli
# using npm
npm install -g @medusajs/medusa-cli
# initialise a Medusa project
medusa new my-medusa-store
```
@@ -87,22 +88,14 @@ Additionally, add Strapi to your list of plugins:
And finally, install the plugin using your package manager:
```bash
#using yarn
yarn add medusa-plugin-strapi
# using npm
```bash npm2yarn
npm install medusa-plugin-strapi
```
You've now successfully installed and configured your Medusa store engine. Seed it with data and start it up by running:
```bash
# using npm
npm run seed && npm start
# using yarn
yarn seed && yarn start
```bash npm2yarn
npm run seed && npm run start
```
We'll now turn to the Strapi side of things.
@@ -111,13 +104,16 @@ We'll now turn to the Strapi side of things.
Similar to how you installed Medusa, you can install Strapi using your favorite package manager. Use the `strapi-medusa-template` to create your project. The template is a custom Strapi implementation required for the two systems to work together.
You can use NPX:
```bash
# using npx
npx create-strapi-app@3.6.8 strapi-medusa --template https://github.com/Deathwish98/strapi-medusa-template.git
```
# using yarn
Alternatively, using Yarn:
```bash
yarn global add create-strapi-app@3.6.8
create-strapi-app strapi-medusa --template https://github.com/Deathwish98/strapi-medusa-template.git
```

402
docs/content/add-plugins/stripe.md
View File

@@ -1,6 +1,10 @@
# Stripe
[View plugin here](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-stripe)
This document guides you through setting up Stripe payments in your Medusa server, admin, and storefront using the [Stripe Plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-stripe).
## Video Guide
You can also follow our video guide to learn how the setup works:
<div>
<video width="100%" height="100%" playsinline autoplay muted controls>
@@ -8,114 +12,364 @@
</video>
</div>
### Introduction
## Overview
Handling payments is at the core of every commerce system; it allows us to run our businesses. Consequently, a vast landscape of payment providers has developed, each with varying cost models, implementational specifications, and analytical capabilities.
[Stripe](https://stripe.com/) is a battle-tested and unified platform for transaction handling. Stripe supplies you with the technical components needed to handle transactions safely and all the analytical features necessary to gain insight into your sales. These features are also available in a safe test environment which allows for a concern-free development process.
As a consequence, one might ask, which one(s) should I choose? Medusa makes exchanging enabled payment providers easy through its unified payment API. Here, one may select payment provider plugins already existing ([PayPal](https://docs.medusajs.com/add-plugins/paypal), [Klarna](https://docs.medusajs.com/add-plugins/klarna), and Stripe), or develop new ones.
Using the `medusa-payment-stripe` plugin, this guide shows you how to set up your Medusa project with Stripe as a payment provider.
Using the `medusa-payment-stripe` plugin, this guide will show you how to set up your Medusa project with Stripe as a payment provider.
## Prerequisites
[Stripe](https://stripe.com) is a battle-tested and unified platform for transaction handling. Stripe supplies you with the technical components needed to handle transactions safely and all the analytical features necessary to gain insight into your sales. These features are also available in a safe test environment which allows for a concern free development process.
Before you proceed with this guide, make sure you create a [Stripe account](https://stripe.com). You’ll later retrieve the API Keys and secrets from your account to connect Medusa to your Stripe account.
### Prerequisites
## Medusa Server
This guide assumes that you have set up a medusa project (See [this guide](https://docs.medusajs.com/tutorial/creating-your-medusa-server)). Furthermore, this guide will be using the Gatsby starter as our storefront (See [this guide](https://docs.medusajs.com/starters/gatsby-medusa-starter)) and the Admin panel to manage our store (See the github installation guide [here](https://github.com/medusajs/admin)).
This section guides you over the steps necessary to add Stripe as a payment provider to your Medusa server.
### Installation
If you don’t have a Medusa server installed yet, you must follow our [quickstart guide](../quickstart/quick-start) first.
The first step is to install the `medusa-payment-stripe` plugin in your Medusa project using your favorite package manager:
### Plugin Installation
```bash
# yarn
yarn add medusa-payment-stripe
In the root of your Medusa server, run the following command to install the stripe plugin:
# npm
```bash npm2yarn
npm install medusa-payment-stripe
```
Then in your `medusa-config.js` , add the plugin to your `plugins` array:
### Plugin Configuration
```javascript
module.exports = {
// ... other options
plugins: [
// ... other plugins
{
resolve: `medusa-payment-stripe`,
options: {
api_key: STRIPE_API_KEY,
webhook_secret: STRIPE_WEBHOOK_SECRET,
},
},
];
Next, you need to add configurations for your stripe plugin.
In `medusa-config.js` add the following at the end of the `plugins` array:
```jsx
const plugins = [
...,
{
resolve: `medusa-payment-stripe`,
options: {
api_key: STRIPE_API_KEY,
webhook_secret: STRIPE_WEBHOOK_SECRET,
},
},
];
```
:::note
You might find that this code is already available but commented out. You can proceed with removing the comments instead of adding the code again.
:::
The Stripe plugin uses 2 configuration options. The `api_key` is essential to both your development and production environments. As for the `webhook_secret`, it’s essential for your production environment. So, if you’re only using Stripe for development you can skip adding the value for this option at the moment.
### Retrieving The Keys
On the [dashboard](https://dashboard.stripe.com) of your Stripe account click on the Developers link at the top right. This will take you to the developer dashboard.
You’ll first retrieve the API key. You can find it by choosing API Keys from the sidebar and copying the Secret key.
Next, you need to add the key to your environment variables. In your Medusa server, create `.env` if it doesn’t already exist and add the Stripe key:
```jsx
STRIPE_API_KEY=sk_...
```
:::note
If you store environment variables differently on your server, for example, using the hosting provider’s UI, then you don’t need to add it in `.env`. Add the environment variables in a way relevant to your server.
:::
Next, if you’re installing this plugin for production use, you need to retrieve the Webhook secret. Webhooks allows you to track different events on your Medusa server, such as failed payments.
Go to Webhooks on Stripe’s developer dashboard. Then, choose the Add an Endpoint button.
The endpoint for Stripe’s webhook on your Medusa server is `{SERVER_URL}/stripe/hooks`. So, add that endpoint in its field. Make sure to replace `{SERVER_URL}` with the URL to your server.
Then, you can add a description. You must select at least one event to listen to. Once you’re done, click “Add endpoint”.
After the Webhook is created, you’ll see a key at the top right that starts with `we_...`. Copy that key and in your Medusa server add the Webhook secret environment variable:
```jsx
STRIPE_WEBHOOK_SECRET=we_...
```
## Admin Setup
This section will guide you through adding Stripe as a payment provider in a region using your Medusa admin dashboard.
This step is required for you to be able to use Stripe as a payment provider in your storefront.
### Prerequisites
If you don’t have a Medusa admin installed, make sure to follow along with [the guide on how to install it](https://github.com/medusajs/admin#-quickstart) before continuing with this section.
### Adding Stripe
First, make sure that both your Medusa server and Medusa Admin are running.
Then, in your Medusa Admin, log in and choose Settings from the Sidebar. Then, choose Regions.
![Settings](https://i.imgur.com/wRkmbLY.png)
Then, choose the regions you want to add Stripe as a payment provider. In the right-side settings, scroll down to “Payment Providers” and choose Stripe.
![Choose Stripe](https://i.imgur.com/FH5vgWh.png)
Once you’re done, click Save. Stripe is now a payment provider in your store in the regions you selected.
## Storefront Setup
This guide will take you through how to set up Stripe payments in your Medusa storefront. It includes the steps necessary when using one of Medusa’s official storefronts as well as your own custom React-based storefront.
### Prerequisites
All storefronts require that you obtain your Stripe’s Publishable Key. You can retrieve it from your Stripe’s developer dashboard by choosing API Keys and then copying the Publishable Key.
### Next.js Storefront
Medusa has a Next.js storefront that you can easily use with your Medusa server. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/nextjs-medusa-starter).
In your `.env` file, add the following variable with its value set to the Publishable Key:
```jsx
NEXT_PUBLIC_STRIPE_KEY=pk_...
```
:::note
This variable might be available in your `.env` file but commented out. You can instead remove the comment and change its value.
:::
Now, if you run your Medusa server and your storefront, on checkout you’ll be able to use Stripe.
![Next.js Stripe Form](https://i.imgur.com/1XvW776.png)
### Gatsby Storefront
Medusa also has a Gatsby storefront that you can use as your ecommerce store. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/gatsby-medusa-starter).
In your `.env.development` file (or the file you’re using for your environment variables) add the following variable with the value set to the Publishable Key:
```jsx
GATSBY_STRIPE_KEY=pk_
```
:::note
You might find this environment variable already available so you can just replace its value with your Publishable Key.
:::
Now, if you run your Medusa server and your storefront, on checkout you’ll be able to use Stripe.
![Gatsby Stripe Form](https://i.imgur.com/1XvW776.png)
### Custom Storefront
This section will go over how to add Stripe into a React-based framework. The instructions are general instructions that you can use in your storefront.
#### Workflow Overview
The integration with stripe must have the following workflow:
1. During checkout when the user reaches the payment section, you should [create payment sessions](https://docs.medusajs.com/api/store/cart/initialize-payment-sessions). This will initialize the `payment_sessions` array in the `cart` object received. The `payment_sessions` is an array of available payment providers.
2. If Stripe is available as a payment provider, you should select Stripe as [the payment session](https://docs.medusajs.com/api/store/cart/select-a-payment-session) for the current cart. This will initialize the `payment_session` object in the `cart` object to include data related to Stripe and the current payment session. This includes the payment intent and client secret.
3. After the user enters their card details and submits the form, confirm the payment with Stripe.
4. If the payment is confirmed successfully, [complete the order](https://docs.medusajs.com/api/store/cart/complete-a-cart) in Medusa. Otherwise show an error.
#### Installing Dependencies
Before you start the implementations you need to install the necessary dependencies. You’ll be using Stripe’s React libraries to show the UI and handle the payment confirmation:
```bash npm2yarn
npm install --save @stripe/react-stripe-js @stripe/stripe-js
```
You’ll also use Medusa’s JS Client to easily call Medusa’s REST APIs:
```bash npm2yarn
npm install @medusajs/medusa-js
```
#### Initialize Stripe
In this section, you’ll initialize Stripe without Medusa’s checkout workflow. Please note that this is one approach to add Stripe into your React project. You can check out [Stripe’s React documentation](https://stripe.com/docs/stripe-js/react) for other methods or components.
Create a container component that will hold the payment card component:
```jsx
import { useState } from 'react';
import {Elements} from '@stripe/react-stripe-js';
import Form from './Form';
import {loadStripe} from '@stripe/stripe-js';
const stripePromise = loadStripe('pk_...');
export default function Container() {
const [clientSecret, setClientSecret] = useState()
//TODO set clientSecret
return (
<div>
{clientSecret && (
<Elements stripe={stripePromise} options={{
clientSecret
}}>
<Form clientSecret={clientSecret} cartId={cartId} />
</Elements>
)}
</div>
);
};
```
In this component, you need to use Stripe’s `loadStripe` function outside of the component’s implementation to ensure that Stripe doesn’t re-load with every change. The function accepts the Publishable Key.
:::note
You’ll probably store this Publishable Key in an environment variable depending on your framework. It’s hard-coded here for simplicity.
:::
Then, inside the component’s implementation, you add a state variable `clientSecret` which you’ll retrieve in the next section.
Once the clientSecret is set, the `Elements` Stripe component will wrap a `Form` component you’ll create next. This is necessary because the `Elements` component allows child elements to get access to the card’s inputs and their data using Stripe’s `useElements` hook.
Create a new file for the `Form` component with the following content:
```jsx
import {CardElement, useElements, useStripe} from '@stripe/react-stripe-js';
export default function Form({clientSecret, cartId}) {
const stripe = useStripe();
const elements = useElements();
async function handlePayment(e) {
e.preventDefault()
//TODO handle payment
}
return (
<form>
<CardElement />
<button onClick={handlePayment}>Submit</button>
</form>
);
};
```
This component shows a CardElement component from Stripe’s React library. You can use `stripe` to be able to confirm the payment later. The `elements` variable will be used to retrieve the entered card details safely.
#### Implement the Workflow
You’ll now implement the workflow explained earlier. You’ll use Medusa’s JS Client, so make sure to import it and initialize it in your `Container` component:
```jsx
import Medusa from "@medusajs/medusa-js"
export default function Container() {
const client = new Medusa();
...
}
```
Now head over to [Stripe](https://stripe.com/) and create your account. You can then click API Keys on your dashboard, and here you will see two keys. We suggest using the test environment during development, and therefore you should make sure that you are seeing the keys to the test environment (These keys start with `pk_test_` and `sk_test_` respectively).
:::note
Now open your `.env` file for the Medusa project and store your _secret key_ in the `STRIPE_API_KEY` variable:
In your storefront, you’ll probably be managing the Medusa client through a context for better performance.
```bash
# .env
STRIPE_API_KEY=<your key here>
:::
Then, in the place of the `//TODO` inside the `Container` element, initialize the payment sessions and create a payment session if Stripe is available:
```jsx
client.carts.createPaymentSessions(cart.id)
.then(({cart}) => {
//check if stripe is selected
const isStripeAvailable = cart.payment_sessions?.some((session) => session.provider_id === 'stripe');
if (!isStripeAvailable) {
return;
}
//select stripe payment session
client.carts.setPaymentSession(cart.id, {
provider_id: 'stripe'
}).then(({cart}) => {
setClientSecret(cart.payment_session.data.client_secret);
});
})
```
> Note: For production you should also create a webhook on Stripe (also available on your dashboard) and store its secret in the `STRIPE_WEBHOOK_SECRET` variable. We will go into detail with this in a later guide.
:::note
Then navigate to your Gatsby starter project and open the `.env.development` file and store your _publishable key_ in the `GATSBY_STRIPE_KEY` variable:
Notice that here it’s assumed you have access to the `cart` object throughout your storefront. Ideally, the `cart` should be managed through a context. So, every time the cart is updated, for example, when the `createPaymentSessions` or `setPaymentSession` are called, the cart should be updated in the context to be accessed from other elements. In this case, you probably wouldn’t need a `clientSecret` state variable as you can use the client secret directly from the `cart` object.
```bash
# .env
GATSBY_STRIPE_KEY=<your key here>
:::
Once the client secret is set, the form will be shown to the user.
The last step in the workflow is confirming the payment with Stripe and if it’s done successfully, completing the user’s order. This part is done in the `Form` component.
As you’ll use Medusa’s client again make sure to import it and initialize it:
```jsx
import Medusa from "@medusajs/medusa-js"
export default function Form() {
const client = new Medusa();
...
}
```
### What’s next?
Then, replace the `//TODO` in the `handlePayment` function with the following content:
At this point we have set everything up, and the Stripe payment provider is now enabled in your Medusa project. So, go ahead and start up your medusa project, the gatsby starter, and the admin panel!
```jsx
return stripe.confirmCardPayment(clientSecret, {
payment_method: {
card: elements.getElement(CardElement),
billing_details: {
name,
email,
phone,
address: {
city,
country,
line1,
line2,
postal_code,
}
}
}
}).then(({ error, paymentIntent }) => {
//TODO handle errors
client.carts.complete(cartId).then(resp => console.log(resp))
})
```
However, as Medusa allows for different payment providers in different regions (and multiple providers in each) we should first make Stripe a valid payment option in our default region. To do so, open the admin panel (`http://localhost:7000`) login, and navigate to `Settings > Region settings > Edit Default Region`. Here you should now be able to select Stripe as a payment provider:
You use the `confirmCardPayment` method in the `stripe` object. You’ll need to pass it the client secret, which you can have access to from the cart object if it’s available through the context.
<center>
This method also requires the customer’s information like `name`, `email`, and their address. Make sure to place the values for each based on your implementation.
![Change payment provider](https://i.imgur.com/mVIDYz4.png)
Once the promise resolves you can handle the errors, if there are any. If not, you can complete the customer’s order using `complete` from Medusa’s client. This request expects the cart ID which you should have access to as well.
</center>
If you run your server and storefront now, you’ll see the Stripe UI element and you’ll be able to make orders.
After doing this, and clicking save, we are ready to accept payments using Stripe. So, navigate to your storefront (`http://localhost:8000`) and go through the checkout process:
![Stripe Form](https://i.imgur.com/NOi8THw.png)
<center>
## Capturing Payment
![Checkout process](https://i.imgur.com/qhanISL.gif)
After the customer places an order, you’ll be able to see the order on the admin panel. In the payment information under the “Payment” section, you should see a “Capture” button.
</center>
After doing so, you should be able to see an uncaptured payment in Stripe. Here, you navigate to the payments tab, where you should see the following (depending on your choices during the checkout process):
![Capture Payment](https://i.imgur.com/Iz55PVZ.png)
<center>
Clicking this button allows you to capture the payment for an order. You can also refund payments if an order has captured payments.
![Uncaptured payment](https://i.imgur.com/LX6UR40.png)
Refunding or Capturing payments is reflected in your Stripe’s dashboard as well. This gives you access to all of Stripe’s analytical capabilities.
</center>
## What’s Next 🚀
To then capture the payment, navigate back to the admin panel (`http://localhost:7000/`), and dig into the relevant order, and capture the payment:
<center>
![Capture payment](https://i.imgur.com/y5UxxpS.gif)
</center>
The capture is then reflected in the payment overview in Stripe as well, giving you access to all of Stripe's analytical capabilities:
<center>
![Captured payment](https://i.imgur.com/edv84Nq.png)
</center>
### Summary
In this guide we have setup Stripe as a payment provider giving you a fully functioning ecommerce experience! Interested in learning more? Check out the other guides and tutorials or head over to our [Discord channel](https://discord.gg/xpCwq3Kfn8) if you have any questions or want to become part of our community!
[View plugin here](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-stripe)
- Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store.

128
docs/content/add-plugins/twilio-sms.md Normal file
View File

@@ -0,0 +1,128 @@
# 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 server set up. You can follow our [Quickstart guide](../quickstart/quick-start.md) 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 3 from your [Twilio Console’s homepage](https://console.twilio.com).
## Install Plugin
In the directory of your Medusa server, 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
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 server. To send SMS using it, all you have to do is resolve it in your file as explained in the [Services](../advanced/backend/services/create-service.md#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 install and configure Redis on your server. You can refer to the [development guide](../tutorial/0-set-up-your-development-environment.md#redis) to learn how to do that.
:::
Create the file `src/services/sms.js` in your Medusa server with the following content:
```jsx
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 one of our [Next.js](../starters/nextjs-medusa-starter.md) or [Gatsby](../starters/gatsby-medusa-starter.md) storefronts.
:::
:::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).
:::
![Twilio Dashboard](https://i.imgur.com/MXtQMiL.png)
## What’s Next 🚀
- Learn more about how [Notifications work in Medusa](../how-to/notification-api).
- Install the [Medusa admin](../admin/quickstart.md) for functionalities like Gift Cards creation, swaps, claims, order return requests, and more.

151
docs/content/admin/quickstart.md Normal file
View File

@@ -0,0 +1,151 @@
---
title: Medusa Admin Quickstart
---
# Admin Quickstart
This document will guide you through setting up the Medusa admin in minutes, as well as some of its features.
## Prerequisites
The Medusa admin is connected to the Medusa server. So, make sure to install the Medusa server first before proceeding with the admin. You can check out the [quickstart guide to install the Medusa server](../quickstart/quick-start).
:::tip
If you’re not very familiar with Medusa’s architecture, you can learn more about it in the [Architecture Overview](../introduction#architecture-overview).
:::
## Install the Admin
Start by cloning the [Admin GitHub repository](https://github.com/medusajs/admin) and changing to the cloned directory:
```bash
git clone https://github.com/medusajs/admin medusa-admin
cd medusa-admin
```
Then, install the dependencies:
```bash npm2yarn
npm install
```
## Test it Out
Before running your Medusa admin, make sure that your Medusa server is running.
:::tip
To run your Medusa server, go to the directory holding the server and run:
```bash npm2yarn
npm run start
```
:::
Then, in the directory holding your Medusa admin, run the following to start the development server:
```bash npm2yarn
npm run start
```
By default, the admin runs on port 7000. So, in your browser, go to `localhost:7000` to view your admin.
![Admin Log In](https://i.imgur.com/XYqMCo9.png)
Use your Medusa admin’s user credentials to log in.
:::tip
If you installed the demo data when you installed the Medusa server by using the `--seed` option or running:
```bash npm2yarn
npm run seed
```
You can use the email `admin@medusa-test.com` and password `supersecret` to log in.
:::
## Create a New Admin User
To create a new admin user from the command line, run the following command in the directory holding your Medusa server:
```bash
medusa user -e some@email.com -p some-password
```
This will create a new user that you can use to log into your admin panel.
## Changing the Default Port
The default port is set in `package.json` in the `develop` script:
```json
"develop": "gatsby develop -p 7000",
```
If you wish to change the port you can simply change the `7000` to your desired port.
However, if you change your Medusa admin port, you need to change it in your Medusa server. The Medusa server has the Medusa admin and store URLs set in the configurations to avoid CORS issues.
To change the URL of the Medusa admin in the server, add a new environment variable `ADMIN_CORS` or modify it if you already have it to your Admin URL:
```bash
ADMIN_CORS=<YOUR_ADMIN_URL>
```
Make sure to replace `<YOUR_ADMIN_URL>` with your URL.
## Admin Features Overview
### Order Management
In the Medusa admin, you can view all orders in your store and their details. You can fulfill orders, capture payments, and track order history. You can also create and manage return requests, swaps, and claims.
![Order Management](https://i.imgur.com/aE0wOHA.png)
### Product Management
In the Medusa admin, you can manage your store’s products. You can create products, add their description and images, create variants with multiple options, set different prices for different currencies, and manage inventory.
:::note
To upload images and save products, you need to integrate a file storage plugin. You can use [DigitalOcean Spaces](../add-plugins/spaces), [S3](../add-plugins/s3), or [MinIO](../add-plugins/minio).
:::
![Product Management](https://i.imgur.com/hgqqv4p.png)
### Customer Management
In the Medusa admin, you can manage your store’s customers. You can manage their information and get a close-up on their orders.
![Customer Management](https://i.imgur.com/bPAImGY.png)
### Discounts Management
In the Medusa admin, you can manage your store’s discounts. You can create and manage discounts created for all products or specific products. Discounts can also be of a fixed amount or free shipping. You can also customize the discount code, its expiry date, its description, and more.
![Discounts Management](https://i.imgur.com/CUUcLba.png)
### Gift Cards Management
In the Medusa admin, you can manage your store’s gift card products. You can create a gift card product with images and descriptions. You can specify unlimited denominations as well.
![Gift Cards Management](https://i.imgur.com/243IhXA.png)
### Settings Management
In the Medusa admin, you can manage your store’s overall settings. These include your store’s regions, fulfillment providers, payment providers, your store’s users, and more.
![Settings Management](https://i.imgur.com/MJc92CU.png)
## What’s Next 🚀
- Install the [Next.js](../starters/nextjs-medusa-starter.md) or [Gatsby](../starters/gatsby-medusa-starter.md) storefront starters.
- [Learn how you can use `create-medusa-app` to install all of Medusa’s 3 components.](../how-to/create-medusa-app.md)

22
docs/content/advanced/backend/endpoints/add-admin.md
View File

@@ -36,7 +36,15 @@ This exports a function that returns an Express router. In that function, you ca
Now, if you run your server and send a request to `/admin/hello`, you will receive a JSON response message.
> Custom endpoints are compiled into the `dist` directory of your Backend when you run your server using `medusa develop`, while it’s running, and when you run `npm run build`.
:::note
Custom endpoints are compiled into the `dist` directory of your Backend when you run your server using `medusa develop`, while it’s running, and when you run:
```bash npm2yarn
npm run build
```
:::
## Accessing Endpoints from Admin
@@ -198,6 +206,18 @@ const userService = req.scope.resolve("userService")
const user = await userService.retrieve(id)
```
### Route Parameters
The routes you create receive 2 parameters. The first one is the absolute path to the root directory that your server is running from. The second one is an object that has your plugin's options. If your API route is not implemented in a plugin, then it will be an empty object.
```js
export default (rootDirectory, pluginOptions) => {
const router = Router()
//...
}
```
## What’s Next 🚀
- [Learn how to add an endpoint for the Storefront.](/advanced/backend/endpoints/add-storefront)

22
docs/content/advanced/backend/endpoints/add-storefront.md
View File

@@ -36,7 +36,15 @@ This exports a function that returns an Express router. In that function, you ca
Now, if you run your server and send a request to `/store/hello`, you will receive a JSON response message.
> Custom endpoints are compiled into the `dist` directory of your Backend when you run your server using `medusa develop`, while it’s running, and when you run `npm run build`.
:::note
Custom endpoints are compiled into the `dist` directory of your Backend when you run your server using `medusa develop`, while it’s running, and when you run:
```bash npm2yarn
npm run build
```
:::
## Multiple Endpoints
@@ -169,6 +177,18 @@ const customerService = req.scope.resolve("customerService")
const customer = await customerService.retrieve(id)
```
### Route Parameters
The routes you create receive 2 parameters. The first one is the absolute path to the root directory that your server is running from. The second one is an object that has your plugin's options. If your API route is not implemented in a plugin, then it will be an empty object.
```js
export default (rootDirectory, pluginOptions) => {
const router = Router()
//...
}
```
## What’s Next :rocket:
- [Learn how to add an endpoint for the Admin.](/advanced/backend/endpoints/add-admin)

12
docs/content/guides/checkouts.md → docs/content/advanced/backend/payment/frontend-payment-flow-in-checkout.md
View File

@@ -1,12 +1,12 @@
---
title: Checkouts
---
# Checkouts
# Frontend Payment Flow in Checkout
## Introduction
The purpose of this guide is to describe a checkout flow in Medusa. It is assumed that you've completed our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or [Tutorial](https://docs.medusajs.com/tutorial/set-up-your-development-environment) and are familiar with the technologies we use in our stack. Additionally, having an understanding of the [core API](https://docs.medusajs.com/api/store/auth) would serve as a great foundation for this walkthrough.
> All code snippets in the following guide, use the JS SDK distributed through **npm**. To install it, run `yarn add @medusajs/medusa-js` or `npm install @medusajs/medusa-js`.
> All code snippets in the following guide, use the JS SDK distributed through **npm**. To install it, run:
```bash npm2yarn
npm install @medusajs/medusa-js
```
## Glossary
- **Cart**: The Cart contains all the information needed for customers to complete an Order. In the Cart customers gather the items they wish to purchase, they add shipping and billing details and complete payment information.

387
docs/content/advanced/backend/payment/how-to-create-payment-provider.md Normal file
View File

@@ -0,0 +1,387 @@
# How to Create a Payment Provider
In this document, you’ll learn how to add a Payment Provider to your Medusa server. If you’re unfamiliar with the Payment architecture in Medusa, make sure to check out the [overview](./overview.md) first.
## Overview
A Payment Provider is the payment method used to authorize, capture, and refund payment, among other actions. An example of a Payment Provider is Stripe.
By default, Medusa has a [manual payment provider](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-fulfillment-manual) that has minimal implementation. It can be synonymous with a Cash on Delivery payment method. It allows store operators to manage the payment themselves but still keep track of its different stages on Medusa.
Adding a Payment Provider is as simple as creating a [service](../services/create-service.md) file in `src/services`. A Payment Provider is essentially a service that extends `PaymentService` from `medusa-interfaces`.
Payment Provider Services must have a static property `identifier`. It is the name that will be used to install and refer to the Payment Provider in the Medusa server.
:::tip
Payment Providers are loaded and installed at the server startup.
:::
The Payment Provider service is also required to implement the following methods:
1. `createPayment`: Called when a Payment Session for the Payment Provider is to be created.
2. `retrievePayment`: Used to retrieve payment data from the third-party provider, if there’s any.
3. `getStatus`: Used to get the status of a Payment or Payment Session.
4. `updatePayment`: Used to update the Payment Session whenever the cart and its related data are updated.
5. `updatePaymentData`: Used to update the `data` field of Payment Sessions. Specifically called when a request is sent to the [Update Payment Session](https://docs.medusajs.com/api/store/cart/update-a-payment-session) endpoint.
6. `deletePayment`: Used to perform any action necessary before a Payment Session is deleted.
7. `authorizePayment`: Used to authorize the payment amount of the cart before the order or swap is created.
8. `getPaymentData`: Used to retrieve the data that should be stored in the `data` field of a new Payment instance after the payment amount has been authorized.
9. `capturePayment`: Used to capture the payment amount of an order or swap.
10. `refundPayment`: Used to refund a payment amount of an order or swap.
11. `cancelPayment`: Used to perform any necessary action with the third-party payment provider when an order or swap is canceled.
:::note
All these methods must be declared async in the Payment Provider Service.
:::
These methods are used at different points in the Checkout flow as well as when processing the order after it’s placed.
![Payment Flows.jpg](https://i.imgur.com/WeDr0ph.jpg)
## Create a Fulfillment Provider
The first step to create a fulfillment provider is to create a file in `src/services` with the following content:
```jsx
import { PaymentService } from "medusa-interfaces"
class MyPaymentService extends PaymentService {
}
export default MyPaymentService;
```
Where `MyPaymentService` is the name of your Payment Provider service. For example, Stripe’s Payment Provider Service is called `StripeProviderService`.
Payment Providers must extend `PaymentService` from `medusa-interfaces`.
:::tip
Following the naming convention of Services, the name of the file should be the slug name of the Payment Provider, and the name of the class should be the camel case name of the Payment Provider suffixed with “Service”. In the example above, the name of the file should be `my-payment.js`. You can learn more in the [service documentation](../services/create-service.md).
:::
### Identifier
As mentioned in the overview, Payment Providers should have a static `identifier` property.
The `PaymentProvider` model has 2 properties: `identifier` and `is_installed`. The value of the `identifier` property in the class will be used when the Payment Provider is created in the database.
The value of this property will also be used to reference the Payment Provider throughout the Medusa server. For example, the identifier is used when a [Payment Session in a cart is selected on checkout](https://docs.medusajs.com/api/store/cart/select-a-payment-session).
### constructor
You can use the `constructor` of your Payment Provider to have access to 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 Payment Provider as an external plugin to be installed on any Medusa server and you want to access the options added for the plugin, you can access it in the constructor. The options are passed as a second parameter:
```jsx
constructor({}, options) {
//you can access options here
}
```
### createPayment
This method is called during checkout when [Payment Sessions are initialized](https://docs.medusajs.com/api/store/cart/initialize-payment-sessions) to present payment options to the customer. It is used to allow you to make any necessary calls to the third-party provider to initialize the payment. For example, in Stripe this method is used to initialize a Payment Intent for the customer.
The method receives the cart as an object for its first parameter. It holds all the necessary information you need to know about the cart and the customer that owns this cart.
This method must return an object that is going to be stored in the `data` field of the Payment Session to be created. As mentioned in the [Architecture Overview](./overview.md), the `data` field is useful to hold any data required by the third-party provider to process the payment or retrieve its details at a later point.
An example of a minimal implementation of `createPayment` that does not interact with any third-party providers:
```jsx
async createPayment(cart) {
return {
id: 'test-payment',
status: 'pending'
};
}
```
### retrievePayment
This method is used to provide a uniform way of retrieving the payment information from the third-party provider. For example, in Stripe’s Payment Provider Service this method is used to retrieve the payment intent details from Stripe.
This method accepts the `data` field of a Payment Session or a Payment. So, you should make sure to store in the `data` field any necessary data that would allow you to retrieve the payment data from the third-party provider.
This method must return an object containing the data from the third-party provider.
An example of a minimal implementation of `retrievePayment` where you don’t need to interact with the third-party provider:
```jsx
async retrievePayment(cart) {
return {};
}
```
### getStatus
This method is used to get the status of a Payment or a Payment Session.
Its main usage is in the place order workflow. If the status returned is not `authorized`, then the payment is considered failed, an error will be thrown, and the order will not be placed.
This method accepts the `data` field of the Payment or Payment Session as a parameter. You can use this data to interact with the third-party provider to check the status of the payment if necessary.
This method returns a string that represents the status. The status must be one of the following values:
1. `authorized`: The payment was successfully authorized.
2. `pending`: The payment is still pending. This is the default status of a Payment Session.
3. `requires_more`: The payment requires more actions from the customer. For example, if the customer must complete a 3DS check before the payment is authorized.
4. `error`: If an error occurred with the payment.
5. `canceled`: If the payment was canceled.
An example of a minimal implementation of `getStatus` where you don’t need to interact with the third-party provider:
```jsx
async getStatus (data) {
return data.status;
}
```
:::note
This code block assumes the status is stored in the `data` field as demonstrated in the `createPayment` method.
:::
### updatePayment
This method is used to perform any necessary updates on the payment. This method is called whenever the cart or any of its related data is updated. For example, when a [line item is added to the cart](https://docs.medusajs.com/api/store/cart/add-a-line-item) or when a [shipping method is selected](https://docs.medusajs.com/api/store/cart/add-a-shipping-method).
:::tip
A line item refers to a product in the cart.
:::
It accepts the `data` field of the Payment Session as the first parameter and the cart as an object for the second parameter.
You can utilize this method to interact with the third-party provider and update any details regarding the payment if necessary.
This method must return an object that will be stored in the `data` field of the Payment Session.
An example of a minimal implementation of `updatePayment` that does not need to make any updates on the third-party provider or the `data` field of the Payment Session:
```jsx
async updatePayment(sessionData, cart) {
return sessionData;
}
```
### updatePaymentData
This method is used to update the `data` field of a Payment Session. Particularly, it is called when a request is sent to the [Update Payment Session](https://docs.medusajs.com/api/store/cart/update-a-payment-session) endpoint. This endpoint receives a `data` object in the body of the request that should be used to update the existing `data` field of the Payment Session.
This method accepts the current `data` field of the Payment Session as the first parameter, and the new `data` field sent in the body request as the second parameter.
You can utilize this method to interact with the third-party provider and make any necessary updates based on the `data` field passed in the body of the request.
This method must return an object that will be stored in the `data` field of the Payment Session.
An example of a minimal implementation of `updatePaymentData` that returns the `updatedData` passed in the body of the request as-is to update the `data` field of the Payment Session.
```jsx
async updatePaymentData(sessionData, updatedData) {
return updatedData;
}
```
### deletePayment
This method is used to perform any actions necessary before a Payment Session is deleted. The Payment Session is deleted in one of the following cases:
1. When a request is sent to [delete the Payment Session](https://docs.medusajs.com/api/store/cart/delete-a-payment-session).
2. When the [Payment Session is refreshed](https://docs.medusajs.com/api/store/cart/refresh-a-payment-session). The Payment Session is deleted so that a newer one is initialized instead.
3. When the Payment Provider is no longer available. This generally happens when the store operator removes it from the available Payment Provider in the admin.
4. When the region of the store is changed based on the cart information and the Payment Provider is not available in the new region.
It accepts the Payment Session as an object for its first parameter.
You can use this method to interact with the third-party provider to delete data related to the Payment Session if necessary.
An example of a minimal implementation of `deletePayment` where no interaction with a third-party provider is required:
```jsx
async deletePayment(paymentSession) {
return;
}
```
### authorizePayment
This method is used to authorize payment using the Payment Session for an order. This is called when the [cart is completed](https://docs.medusajs.com/api/store/cart/complete-a-cart) and before the order is created.
This method is also used for authorizing payments of a swap of an order.
The payment authorization might require additional action from the customer before it is declared authorized. Once that additional action is performed, the `authorizePayment` method will be called again to validate that the payment is now fully authorized. So, you should make sure to implement it for this case as well, if necessary.
Once the payment is authorized successfully and the Payment Session status is set to `authorized`, the order can then be placed.
If the payment authorization fails, then an error will be thrown and the order will not be created.
:::note
The payment authorization status is determined using the `getStatus` method as mentioned earlier. If the status is `requires_more` then it means additional actions are required from the customer. If the workflow process reaches the “Start Create Order” step and the status is not `authorized`, then the payment is considered failed.
:::
This method accepts the Payment Session as an object for its first parameter, and a `context` object as a second parameter. The `context` object contains the following properties:
1. `ip`: The customer’s IP.
2. `idempotency_key`: The [Idempotency Key](./overview.md#idempotency-key) that is associated with the current cart. It is useful when retrying payments, retrying checkout at a failed point, or for payments that require additional actions from the customer.
This method must return an object containing the property `status` which is a string that indicates the current status of the payment, and the property `data` which is an object containing any additional information required to perform additional payment processing such as capturing the payment. The values of both of these properties are stored in the Payment Session’s `status` and `data` fields respectively.
You can utilize this method to interact with the third-party provider and perform any actions necessary to authorize the payment.
An example of a minimal implementation of `authorizePayment` that doesn’t need to interact with any third-party provider:
```jsx
async authorizePayment(paymentSession, context) {
return {
status: 'authorized',
data: {
id: 'test'
}
};
}
```
### getPaymentData
After the payment is authorized using `authorizePayment`, a Payment instance will be created. The `data` field of the Payment instance will be set to the value returned from the `getPaymentData` method in the Payment Provider.
This method accepts the Payment Session as an object for its first parameter.
This method must return an object to be stored in the `data` field of the Payment instance. You can either use it as-is or make any changes to it if necessary.
An example of a minimal implementation of `getPaymentData`:
```jsx
async getPaymentData(paymentSession) {
return paymentSession.data;
}
```
### capturePayment
This method is used to capture the payment amount of an order. This is typically triggered manually by the store operator from the admin.
This method is also used for capturing payments of a swap of an order.
You can utilize this method to interact with the third-party provider and perform any actions necessary to capture the payment.
This method accepts the Payment as an object for its first parameter.
This method must return an object that will be stored in the `data` field of the Payment.
An example of a minimal implementation of `capturePayment` that doesn’t need to interact with a third-party provider:
```jsx
async capturePayment(payment) {
return {
status: 'captured'
};
}
```
### refundPayment
This method is used to refund an order’s payment. This is typically triggered manually by the store operator from the admin. The refund amount might be the total order amount or part of it.
This method is also used for refunding payments of a swap of an order.
You can utilize this method to interact with the third-party provider and perform any actions necessary to refund the payment.
This method accepts the Payment as an object for its first parameter, and the amount to refund as a second parameter.
This method must return an object that is stored in the `data` field of the Payment.
An example of a minimal implementation of `refundPayment` that doesn’t need to interact with a third-party provider:
```jsx
async refundPayment(payment, amount) {
return {
id: 'test'
}
}
```
### cancelPayment
This method is used to cancel an order’s payment. This method is typically triggered by one of the following situations:
1. Before an order is placed and after the payment is authorized, an inventory check is done on products to ensure that products are still available for purchase. If the inventory check fails for any of the products, the payment is canceled.
2. If the store operator cancels the order from the admin.
This method is also used for canceling payments of a swap of an order.
You can utilize this method to interact with the third-party provider and perform any actions necessary to cancel the payment.
This method accepts the Payment as an object for its first parameter.
This method must return an object that is stored in the `data` field of the Payment.
An example of a minimal implementation of `cancelPayment` that doesn’t need to interact with a third-party provider:
```jsx
async cancelPayment(payment) {
return {
id: 'test'
}
}
```
## Optional Methods
### retrieveSavedMethods
This method can be added to your Payment Provider service if your third-party provider supports saving the customer’s payment methods. Please note that in Medusa there is no way to save payment methods.
This method is called when a request is sent to [Retrieve Saved Payment Methods](https://docs.medusajs.com/api/store/customer/retrieve-saved-payment-methods).
This method accepts the customer as an object for its first parameter.
This method returns an array of saved payment methods retrieved from the third-party provider. You have the freedom to shape the items in the array as you see fit since they will be returned as-is for the response to the request.
:::note
If you’re using Medusa’s [Next.js](../../../starters/nextjs-medusa-starter.md) or [Gatsby](../../../starters/gatsby-medusa-starter.md) storefront starters, note that the presentation of this method is not implemented. You’ll need to implement the UI and pages for this method based on your implementation and the provider you are using.
:::
An example of the implementation of `retrieveSavedMethods` taken from Stripe’s Payment Provider:
```jsx
/**
* Fetches a customers saved payment methods if registered in Stripe.
* @param {object} customer - customer to fetch saved cards for
* @returns {Promise<Array<object>>} saved payments methods
*/
async retrieveSavedMethods(customer) {
if (customer.metadata && customer.metadata.stripe_id) {
const methods = await this.stripe_.paymentMethods.list({
customer: customer.metadata.stripe_id,
type: "card",
})
return methods.data
}
return Promise.resolve([])
}
```
## What’s Next 🚀
- Check out the Payment Providers for [Stripe](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-stripe) and [PayPal](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-payment-paypal) for implementation examples.
- Learn more about the [frontend checkout flow](./frontend-payment-flow-in-checkout.md).

130
docs/content/advanced/backend/payment/overview.md Normal file
View File

@@ -0,0 +1,130 @@
# Architecture Overview
In this document, you’ll learn about the payment architecture in Medusa, specifically its 3 main components and the idempotency key.
## Introduction
The payment architecture refers to all operations in an ecommerce store related to processing a customer’s payment. It includes the checkout flow and order handling including refunds and swaps.
In Medusa, there are 3 main components in the payment architecture: Payment Provider, Payment Session, and Payment.
1. A **Payment Provider** is a service or method used to capture, authorize, and refund payments, among other functionalities.
2. A **Payment Session** is a session associated with a cart and created during a customer’s checkout flow. It is controlled by the **Payment Provider** to authorize the payment and is used eventually to create a **Payment**.
3. A **Payment** is associated with an order and it represents the amount authorized for the purchase. It is used later for further payment operations such as capturing or refunding payments.
An important part in the Payment architecture to understand is the **Idempotency Key**. It’s a unique value that’s generated for a cart and is used to retry payments during checkout if they fail.
## Payment Provider
### Overview
A Payment Provider in Medusa is a method to handle payments in selected regions. It is not associated with a cart, customer, or order in particular. It provides the necessary implementation to create Payment Sessions and Payments, as well as authorize and capture payments, among other functionalities.
Payment Providers can be integrated with third-party services that handle payment operations such as capturing a payment. An example of a Payment Provider is Stripe.
Payment Providers can also be related to a custom way of handling payment operations. An example of that is cash on delivery (COD) payment methods or Medusa’s [manual payment provider plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-manual) which provides a minimal implementation of a payment provider and allows store operators to manually handle order payments.
### How it is Created
A Payment Provider is essentially a Medusa [service](../services/create-service.md) with a unique identifier, and it extends the `PaymentService` provided by the `medusa-interfaces` package. It can be created as part of a [plugin](../../../guides/plugins.md), or it can be created just as a service file in your Medusa server.
As a developer, you will mainly work with the Payment Provider when integrating a payment method in Medusa.
When you run your Medusa server, the Payment Provider will be registered on your server if it hasn’t been already.
Once the Payment Provider is added to the server, the store operator will be able to choose on the [Medusa Admin](../../../admin/quickstart.md) the payment providers available in a region. These payment providers are shown to the customer at checkout to choose from and use.
:::caution
It’s important to choose a payment provider in the list of payment providers in a region, or else the payment provider cannot be used by customers on checkout.
:::
### Model Overview
The `PaymentProvider` model only has 2 attributes: `is_installed` to indicate if the payment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Payment Provider service.
## Payment Session
### Overview
Payment Sessions are linked to a customer’s cart. Each Payment Session is associated with a payment provider that is available in the customer cart’s region.
They hold the status of the payment flow throughout the checkout process which can be used to indicate different statuses such as an authorized payment or payment that requires more actions from the customer.
After the checkout process is completed and the Payment Session has been authorized successfully, a Payment instance will be created to be associated with the customer’s order and will be used for further actions related to that order.
### How it is Created
After the customer adds products to the cart, proceeds with the checkout flow, and reaches the payment method section, Payment Sessions are created for each Payment Provider available in that region.
During the creation of the Payment Session, the Payment Provider can interact with third-party services for any initialization necessary on their side. For example, when a Payment Session for Stripe is being created, a payment intent associated with the customer can be created with Stripe as well.
Payment Sessions can hold data that is necessary for the customer to complete their payment.
Among the Payment Sessions available only one will be selected based on the customer’s payment provider choice. For example, if the customer sees that they can pay with Stripe or PayPal and chooses Stripe, Stripe’s Payment Session will be the selected Payment Session of that cart.
### Model Overview
The `PaymentSession` model belongs to a `Cart`. This is the customer‘s cart that was used for checkout which lead to the creation of the Payment Session.
The `PaymentSession` also belongs to a `PaymentProvider`. This is the Payment Provider that was used to create the Payment Session and that controls it for further actions like authorizing the payment.
The `data` attribute is an object that holds any data required for the Payment Provider to perform payment operations like authorizing or capturing payment. For example, when a Stripe payment session is initialized, the `data` object will hold the payment intent among other data necessary to authorize the payment.
The `is_selected` attribute in the `PaymentSession` model is a boolean value that indicates whether this Payment Session was selected by the customer to pay for their purchase. Going back to the previous example of having Stripe and PayPal as the available Payment Providers, when the customer chooses Stripe, Stripe’s Payment Session will have `is_selected` set to true whereas PayPal’s Payment Session will have `is_selected` set to false.
The `status` attributes indicates the current status of the Payment Session. It can be one of the following values:
- `authorized`: The payment has been authorized which means the order can be placed successfully.
- `pending`: The payment is still pending further actions. This is usually used when the payment session is initialized.
- `requires_more`: The payment requires additional actions from the customer before the payment can be authorized successfully and the order can be placed. An example of this is payment methods that require 3-D Secure checks.
- `error`: An error was encountered when an authorization was attempted. This status is usually used when an error has been encountered when authorizing the payment with a third-party payment provider.
- `canceled`: The payment has been canceled.
These statuses are important in the checkout flow to determine the current step the customer is at and which action should come next. For example, if there is an attempt to place the order but the status of the Payment Session is not `authorized`, an error will be thrown.
## Payment
### Overview
A Payment is used to represent the amount authorized for a customer’s purchase. It is associated with the order placed by the customer and will be used after that for all operations related to the order’s payment such as capturing or refunding the payment.
Payments are generally created using data from the Payment Session and it holds any data that can be necessary to perform later payment operations.
### How it is Created
Once the customer completes their purchase and the payment has been authorized, a Payment instance will be created from the Payment Session. The Payment is associated first with the cart and then with the order once it’s created and placed.
When the store operator then chooses to capture the order from the Medusa Admin, the Payment is used by the Payment Provider to capture the payment. This is the same case for refunding the amount, canceling the order, or creating a swap.
### Model Overview
The `Payment` model belongs to the `Cart` that it was originally created from when the customer’s payment was authorized. It also belongs to an `Order` once it’s placed. Additionally, it belongs to a `PaymentProvider` which is the payment provider that the customer chose on checkout.
In case a `Swap` is created for an order, `Payment` will be associated with that swap to handle payment operations related to it.
Similar to `PaymentSession`, `Payment` has a `data` attribute which is an object that holds any data required to perform further actions with the payment such as capturing the payment.
`Payment` also holds attributes like `amount` which is the amount authorized for payment, and `amount_refunded` which is the amount refunded from the original amount if a refund has been initiated.
Additionally, `Payment` has the `captured_at` date-time attribute which is filled when the payment has been captured, and a `canceled_at` date-time attribute which is filled when the order has been canceled.
## Idempotency Key
An Idempotency Key is a unique key associated with a cart. It is generated at the last step of checkout before authorization of the payment is attempted.
That Idempotency Key is then set in the header under the `Idempotency-Key` response header field along with the header field `Access-Control-Expose-Headers` set to `Idempotency-Key`.
If an error occurs or the purchase is interrupted at any step, the client can retry the payment by adding the Idempotency Key of the cart as the `Idempotency-Key` header field in their subsequent requests.
The server wraps each essential part of the checkout completion in its own step and stores the current step of checkout with its associated Idempotency Key.
If then the request is interrupted for any reason or the payment fails, the client can retry completing the check out using the Idempotency Key, and the flow will continue from the last stored step.
This prevents any payment issues from occurring with the customers and allows for secure retries of failed payments or interrupted connections.
## What’s Next 🚀
- [Check out how the checkout flow is implemented on the frontend.](./frontend-payment-flow-in-checkout.md)
- Check out payment plugins like [Stripe](../../../add-plugins/stripe.md), [Paypal](../../../add-plugins/paypal.md), and [Klarna](../../../add-plugins/klarna.md).

272
docs/content/advanced/backend/shipping/add-fulfillment-provider.md Normal file
View File

@@ -0,0 +1,272 @@
# How to Add a Fulfillment Provider
In this document, you’ll learn how to add a fulfillment provider to a Medusa server. If you’re unfamiliar with the Shipping architecture in Medusa, make sure to [check out the overview first](https://docs.medusajs.com/advanced/backend/shipping/overview/).
## Overview
A fulfillment provider is the shipping provider used to fulfill orders and deliver them to customers. An example of a fulfillment provider is FedEx.
By default, a Medusa Server has a `manual` fulfillment provider which has minimal implementation. It allows you to accept orders and fulfill them manually. However, you can integrate any fulfillment provider into Medusa, and your fulfillment provider can interact with third-party shipping providers.
Adding a fulfillment provider is as simple as creating one [service](../services/create-service.md) file in `src/services`. A fulfillment provider is essentially a service that extends the `FulfillmentService`. It requires implementing 4 methods:
1. `getFulfillmentOptions`: used to retrieve available fulfillment options provided by this fulfillment provider.
2. `validateOption`: used to validate the shipping option when it’s being created by the admin.
3. `validateFulfillmentData`: used to validate the shipping method when the customer chooses a shipping option on checkout.
4. `createFulfillment`: used to perform any additional actions when fulfillment is being created for an order.
Also, the fulfillment provider class should have a static property `identifier`. It is the name that will be used to install and refer to the fulfillment provider throughout Medusa.
Fulfillment providers are loaded and installed on the server startup.
## Create a Fulfillment Provider
The first step is to create the file that will hold the fulfillment provider class in `src/services`:
```jsx
import { FulfillmentService } from "medusa-interfaces"
class MyFulfillmentService extends FulfillmentService {
}
export default MyFulfillmentService;
```
Fulfillment provider services should extend `FulfillmentService` imported from `medusa-interfaces`.
:::note
Following the naming convention of Services, the name of the file should be the slug name of the fulfillment provider, and the name of the class should be the camel case name of the fulfillment provider suffixed with “Service”. You can learn more in the [service documentation](../services/create-service.md).
:::
### Identifier
As mentioned in the overview, fulfillment providers should have a static `identifier` property.
The `FulfillmentProvider` model has 2 properties: `identifier` and `is_installed`. The `identifier` property in the class will be used when the fulfillment provider is created in the database.
The value of this property will also be used to reference the fulfillment provider throughout Medusa. For example, it is used to [add a fulfillment provider](https://docs.medusajs.com/api/admin/region/add-fulfillment-provider) to a region.
```jsx
import { FulfillmentService } from "medusa-interfaces"
class MyFulfillmentService extends FulfillmentService {
static identifier = 'my-fulfillment';
}
export default MyFulfillmentService;
```
### constructor
You can use the `constructor` of your fulfillment provider to have access to 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 fulfillment provider as an external plugin to be installed on any Medusa server and you want to access the options added for the plugin, you can access it in the constructor. The options are passed as a second parameter:
```jsx
constructor({}, options) {
//you can access options here
}
```
### getFulfillmentOptions
When the admin is creating shipping options available for customers during checkout, they choose one of the fulfillment options provided by underlying fulfillment providers.
For example, if you’re integrating UPS as a fulfillment provider, you might support 2 fulfillment options: UPS Express Shipping and UPS Access Point.
These fulfillment options are defined in the `getFulfillmentOptions` method. This method should return an array of options.
For example:
```jsx
async getFulfillmentOptions () {
return [
{
id: 'my-fulfillment'
},
{
id: 'my-fulfillment-dynamic'
}
];
}
```
When the admin chooses one of those fulfillment options, the data of the chosen fulfillment option is stored in the `data` property of the shipping option created. This property is used to add any additional data you need to fulfill the order with the third-party provider.
For that reason, the fulfillment option does not have any required structure and can be of any format that works for your integration.
### validateOption
Once the admin creates the shipping option, the data will be validated first using this method in the underlying fulfillment provider of that shipping option. This method is called when a `POST` request is sent to `[/admin/shipping-options](https://docs.medusajs.com/api/admin/shipping-option/create-shipping-option)`.
This method accepts the `data` object that is sent in the body of the request. You can use this data to validate the shipping option before it is saved.
This method returns a boolean. If the result is false, an error is thrown and the shipping option will not be saved.
For example, you can use this method to ensure that the `id` in the `data` object is correct:
```jsx
async validateOption (data) {
return data.id == 'my-fulfillment';
}
```
If your fulfillment provider does not need to run any validation, you can simply return `true`.
### validateFulfillmentOption
When the customer chooses a shipping option on checkout, the shipping option and its data are validated before the shipping method is created.
`validateFulfillmentOption` is called when a `POST` request is sent to `[/carts/:id/shipping-methods](https://docs.medusajs.com/api/store/cart/add-a-shipping-method)`.
This method accepts 3 parameters:
1. The shipping option data.
2. The `data` object passed in the body of the request.
3. The customer’s cart data.
You can use these parameters to validate the chosen shipping option. For example, you can check if the `data` object includes all data needed to fulfill the shipment later on.
If any of the data is invalid, you can throw an error. This error will stop Medusa from creating a shipping method and the error message will be returned as a result to the endpoint.
If everything is valid, this method must return a value that will be stored in the `data` property of the shipping method to be created. So, make sure the value you return contains everything you need to fulfill the shipment later on.
For example:
```jsx
async validateFulfillmentData(optionData, data, cart) {
if (data.id !== "my-fulfillment") {
throw new Error("invalid data");
}
return {
...data
}
}
```
### createFulfillment
After an order is placed, it can be fulfilled either manually by the admin or using automation.
This method gives you access to the fulfillment being created as well as other details in case you need to perform any additional actions with the third-party provider.
This method accepts 4 parameters:
1. The data of the shipping method associated with the order.
2. An array of items in the order to be fulfilled. The admin can choose all or some of the items to fulfill.
3. The data of the order
4. The data of the fulfillment being created.
You can use the `data` property in the shipping method (first parameter) to access the data specific to the shipping option. This is based on your implementation of previous methods.
Here is a basic implementation of `createFulfillment` for a fulfillment provider that does not interact with any third-party provider to create the fulfillment:
```jsx
createFulfillment(
methodData,
fulfillmentItems,
fromOrder,
fulfillment
) {
// No data is being sent anywhere
return Promise.resolve({})
}
```
:::note
This method is also used to create claims and swaps. The fulfillment object has the fields `claim_id`, `swap_id`, and `order_id`. You can check which isn’t null to determine what type of fulfillment is being created.
:::
### Useful Methods
The above-detailed methods are the required methods for every fulfillment provider. However, there are additional methods that you can use in your fulfillment provider to customize it further or add additional features.
#### canCalculate
This method validates whether a shipping option is calculated dynamically or flat rate. It is called if the `price_type` of the shipping option being created is set to `calculated`.
If this method returns `true`, that means that the price should be calculated dynamically. The `amount` property of the shipping option will then be set to `null`. The amount will be created later when the shipping method is created on checkout using the `calculatePrice` method (explained next).
If the method returns `false`, an error is thrown as it means the selected shipping option can only be chosen if the price type is set to `flat_rate`.
This method receives as a parameter the `data` object sent with the request that [creates the shipping option.](https://docs.medusajs.com/api/admin/shipping-option/create-shipping-option) You can use this data to determine whether the shipping option should be calculated or not. This is useful if the fulfillment provider you are integrating has both flat rate and dynamically priced fulfillment options.
For example:
```jsx
canCalculate(data) {
return data.id === 'my-fulfillment-dynamic';
}
```
#### calculatePrice
This method is called on checkout when the shipping method is being created if the `price_type` of the selected shipping option is `calculated`.
This method receives 3 parameters:
1. The `data` parameter of the selected shipping option.
2. The `data` parameter sent with [the request](https://docs.medusajs.com/api/store/cart/add-a-shipping-method).
3. The customer’s cart data.
If your fulfillment provider does not provide any dynamically calculated rates you can keep the function empty:
```jsx
calculatePrice() {
}
```
Otherwise, you can use it to calculate the price with a custom logic. For example:
```jsx
calculatePrice (optionData, data, cart) {
return cart.items.length * 1000;
}
```
#### createReturn
Fulfillment providers can also be used to return products. A shipping option can be used for returns if the `is_return` property is `true` or if an admin creates a Return Shipping Option from the settings.
This method is called when the admin [creates a return request](https://docs.medusajs.com/api/admin/order/request-a-return) for an order or when the customer [creates a return of their order](https://docs.medusajs.com/api/store/return/create-return).
It gives you access to the return being created in case you need to perform any additional actions with the third-party provider.
It receives the return created as a parameter. The value it returns is set to the `shipping_data` of the return instance.
This is the basic implementation of the method for a fulfillment provider that does not contact with a third-party provider to fulfill the return:
```jsx
createReturn(returnOrder) {
return Promise.resolve({})
}
```
#### cancelFulfillment
This method is called when a fulfillment is cancelled by the admin. This fulfillment can be for an order, a claim, or a swap.
It gives you access to the fulfillment being canceled in case you need to perform any additional actions with your third-party provider.
This method receives the fulfillment being cancelled as a parameter.
This is the basic implementation of the method for a fulfillment provider that does not interact with a third-party provider to cancel the fulfillment:
```jsx
cancelFulfillment(fulfillment) {
return Promise.resolve({})
}
```
## What’s Next 🚀
- Check out the [Webshipper plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-fulfillment-webshipper) for an example of a fulfillment provider that interacts with a third-party providers.
- Check out the [manual fulfillment plugin](https://github.com/medusajs/medusa/tree/cab5821f55cfa448c575a20250c918b7fc6835c9/packages/medusa-payment-manual) for a basic implementation of a fulfillment provider.

134
docs/content/advanced/backend/shipping/overview.md Normal file
View File

@@ -0,0 +1,134 @@
---
title: Shipping Architecture Overview
---
# Architecture Overview
This document gives an overview of the shipping architecture and its 3 most important components.
## Introduction
In Medusa, the Shipping architecture relies on 3 components: **Shipping Profiles**, **Shipping Options**, and **Shipping Methods**.
The distinction between the 3 is important. It has been carefully planned and put together to support all the different ecommerce use cases and shipping providers that can be integrated.
It’s also constructed to support multiple regions, provide different shipment configurations and options for different product types, provide promotional shipments for your customers, and much more.
## Summary
- **Shipping Profiles:** created by the admin. They are used to group products that should be shipped in a different manner than the default. Shipping profiles can have multiple shipping options.
- S**hipping Options:** created by the admin and belong to a shipping profile. They are specific to certain regions and can have cart conditions. They use an underlying fulfillment provider. Once a customer checks out, they can choose the shipping option that’s available and most relevant to them.
- **Shipping Method:** created when the customer chooses a shipping option on checkout. The shipping method is basically a copy of the shipping option, but with values specific to the customer and the cart it’s associated with. When the order is placed, the shipping method will then be associated with the order and fulfilled based on the integration with the fulfillment provider.
:::note
Fulfillment providers are used to ship the products to your customers, whether physically or virtually. An example of a fulfillment provider would be FedEx.
:::
![Shipping.png](https://i.imgur.com/RnC2esy.png)
## Shipping Profile
### Overview
Shipping profiles are the highest in the hierarchy in the shipping architecture.
Shipping profiles are created by the admin. The admin can specify the name of the shipping profile which will be a name that the customer can see.
A shipping profile is not associated with any fulfillment providers. It has multiple shipping options that can be associated with different providers.
### Purpose
Shipping profiles are used to group products that can be shipped in the same manner.
The default shipping profile is one that groups all of your store’s products. You also get a shipping profile that’s specific to gift cards. This is because, generally speaking, all products would be delivered similarly, whereas gift cards would be delivered in different behavior.
Although this might be the general case, there are still some use cases where you will have a set of products that should be shipped differently than others.
For example, shipping heavy items might be more expensive than others, which would enforce different price rates. In that case, you can create a new shipping profile that groups together heavy products. This would allow you to give these products more suitable price rates when creating their shipping options.
### Model Overview
The `ShippingProfile` model can have a set of `Product` instances. These would be the products the shipping profile is providing shipping options for.
The `ShippingProfile` has a `type` attribute that can be `default`, `gift_card`, or `custom`.
The `ShippingProfile` model also has an array of `ShippingOption` instances.
## Shipping Option
### Overview
After the admin adds a shipping profile, they can add shipping options that belong to that shipping profile from the admin dashboard.
Shipping options have a set of conditions like the region they’re available in or cart-specific conditions. For example, if your company operates in the United States as well as Germany, you might use a different shipping option for each of the two countries.
Among the configurations that the admin has to set when creating a shipping option is specifying the fulfillment provider it uses. This means that when you create a plugin for a fulfillment provider, that provider needs to be chosen as the fulfillment provider of a shipping option to be used in the store.
Shipping options are only shown to a customer during checkout if their cart satisfies the option’s conditions. Also, as they belong to a shipping profile, they’re only shown when products that belong to the same shipping profile are in the cart.
### Purpose
The first purpose that a shipping option has is showing the customer during checkout what shipping options are available for them.
Then, once the customer chooses a shipping option, that shipping option is used to create a shipping method with details specific to the customer and their cart. Then, the shipping method is associated with the cart, and the shipping option remains untouched.
Think of a shipping option as a template defined by the admin that indicates what data and values the shipping method should have when it’s chosen by the customer during checkout.
### Model Overview
The `ShippingOption` model belongs to the `ShippingProfile` model.
The `ShippingOption` model also belongs to a `FulfillmentProvider`. This can be either a custom third-party provider or one of Medusa’s default fulfillment providers.
It has the `price_type` attribute to indicate whether the shipping option’s rate is `calculated` by the provider or a fixed `flat_rate` price. It also has the `amount` attribute to set an amount for the shipping option if the `price_type` is `flat_rate`.
`ShippingOption` also belongs to a `Region`, which resembles one or more countries. This defines where the shipping option is available.
`ShippingOption` has a set of `ShippingOptionRequirement` instances. The `ShippingOptionRequirement` model allows defining cart rules which determine whether the shipping option will be available or not for a customer during checkout. For example, you can set a minimum subtotal amount for a shipping option to be available for a customer’s cart.
The `is_return` attribute is used to indicate whether the shipping option is used for shipping orders or returning orders. Shipping options can only be used for one or the other.
The `data` attribute is used to specify any data necessary for fulfilling the shipment based on the underlying fulfillment provider. When you integrate a fulfillment provider, you can check in that provider’s documentation for any data necessary when creating a new shipment.
The `data` attribute does not have any specific format. It’s up to you to choose whatever data is included here.
## Shipping Method
### Overview
Unlike the previous two components, a shipping method is not created by the admin. It’s created when a `POST` request is sent to `/store/carts/:id/shipping-methods` after the customer chooses a shipping option.
The shipping method will be created based on the chosen shipping option and it’ll be associated with the customer’s cart. Then, when the order is placed, the shipping method is associated with the order.
A shipping method can be fulfilled automatically or manually through the admin dashboard. This is based on the fulfillment provider associated with the shipping option the shipping method is based on.
### Purpose
It’s important to understand the distinction between shipping methods and shipping options. Shipping options are templates created by the admin to indicate what shipping options should be shown to a customer. This provides customization capabilities in a store, as an admin is free to specify configurations for that option such as what fulfillment provider it uses or what are its rates.
When handling the order and fulfilling it, you, as a developer, will be mostly interacting with the shipping method.
This separation allows for developers to implement the custom integration with third-party fulfillment providers as necessary while also ensuring that the admin has full control of their store.
## Model Overview
A lot of the shipping method’s attributes are similar to the shipping option’s attribute.
The `ShippingMethod` model belongs to a `ShippingOption`.
Similar to the `data` attribute explained for the `ShippingOption` model, a `ShippingMethod` has a similar `data` attribute that includes all the data to be sent to the fulfillment provider when fulfilling the order.
The `ShippingMethod` belongs to a `Cart`. This is the cart the customer is checking out with.
The `ShippingMethod` also belongs to the `Order` model. This association is accomplished when the order is placed.
The `ShippingMethod` instance holds a `price` attribute, which will either be the flat rate price or the calculated price.
## What’s Next :rocket:
- [Learn how to Create a Fulfillment Provider.](./add-fulfillment-provider.md)
- Check out [available shipping plugins](https://github.com/medusajs/medusa/tree/master/packages).

92
docs/content/advanced/backend/subscribers/create-subscriber.md Normal file
View File

@@ -0,0 +1,92 @@
---
title: Create a Subscriber
---
# Create a Subscriber
In this document, you’ll learn how you create a subscriber in your Medusa server that listens to events to perform an action.
## Overview
In Medusa, there are events that are emitted when a certain action occurs. For example, if a customer places an order, the `order.placed` event is emitted with the order data.
The purpose of these events is to allow other parts of the platform, or third-party integrations, to listen to those events and perform a certain action. That is done by creating subscribers.
Subscribers register handlers for an events and allows you to perform an action when that event occurs. For example, if you want to send your customer an email when they place an order, then you can listen to the `order.placed` event and send the email when the event is emitted.
Natively in Medusa there are subscribers to handle different events. However, you can also create your own custom subscribers.
Custom subscribers reside in your project's `src/subscribers` directory. Files here should export classes, which will be treated as subscribers by Medusa. By convention, the class name should end with `Subscriber` and the file name should be the camel-case version of the class name without `Subscriber`. For example, the `WelcomeSubscriber` class is in the file `src/subscribers/welcome.js`.
Whenever an event is emitted, the subscriber’s registered handler method is executed. The handler method receives as a parameter an object that holds data related to the event. For example, if an order is placed the `order.placed` event will be emitted and all the handlers will receive the order id in the parameter object.
## Prerequisites
Medusa's event system works by pushing data to a Queue that each handler then gets notified of. The queuing system is based on Redis and you will therefore need to make sure that [Redis](https://redis.io) is installed and configured for your Medusa project.
Then, you need to set your Redis URL in your Medusa server. By default, the Redis URL is `redis://localhost:6379`. If you use a different one, set the following environment variable in `.env`:
```bash
REDIS_URL=<YOUR_REDIS_URL>
```
After that, in `medusa-config.js`, you’ll need to comment out the following line:
```jsx
module.exports = {
projectConfig: {
redis_url: REDIS_URL, //this line is commented out
...
}
}
```
After that, you are able to listen to events on your server.
## Implementation
After creating the file under `src/subscribers`, in the constructor of your subscriber, you should 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 which is created in `src/subscribers/orderNotifier.js`:
```jsx
class OrderNotifierSubscriber {
constructor({ eventBusService }) {
eventBusService.subscribe("order.placed", this.handleOrder);
}
handleOrder = async (data) => {
console.log("New Order: " + data.id)
};
}
export default OrderNotifierSubscriber;
```
This subscriber will register 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, and it will receive the order ID in the `data` parameter. You can then use the order’s details to perform any kind of task you need.
> The `data` object will not contain other order data. Only the ID of the order. You can retrieve the order information using the `orderService`.
## Using Services in Subscribers
You can access any service through the dependencies injected to your subscriber’s constructor.
For example:
```jsx
constructor({ productService, eventBusService }) {
this.productService = productService;
eventBusService.subscribe("order.placed", this.handleOrder);
}
```
You can then use `this.productService` anywhere in your subscriber’s methods.
## What’s Next 🚀
- [Learn how to create a service.](/advanced/backend/services/create-service)

4
docs/content/guides/file-plugin.md
View File

@@ -62,7 +62,7 @@ api_secret: "xx"
The first step in creating a plugin is to initialize the Node.js project:
```bash
```bash npm2yarn
npm init
```
@@ -70,7 +70,7 @@ This command will ask you to fill out your project's metadata, which will eventu
Next up, we need to install cloudinary's Node.js SDK.
```bash
```bash npm2yarn
npm install cloudinary
```

12
docs/content/guides/plugins.md
View File

@@ -22,7 +22,7 @@ A plugin is essentially a Node.js project of their own. They contain a file in r
The first step in creating a plugin is to initialize the Node.js project:
```bash
```bash npm2yarn
npm init
```
@@ -88,7 +88,11 @@ Official Medusa plugins can be found within the [mono repo](https://github.com/m
Note: For plugins to become a part of the mono repo, we require you to submit a PR request. If approved, we will publish it under the Medusa organisation on Github.
Plugins are distributed as NPM packages making it possible for developers to simply install and use a plugin via `yarn add` or `npm install`.
Plugins are distributed as NPM packages making it possible for developers to simply install and use a plugin via:
```bash npm2yarn
npm install
```
After installing a plugin using your preferred package manager, it should be added to `medusa-config.js`. We allow you to provide options for plugins. These options can be used for anything ranging from provider requirements such as API keys or custom configuration used in the plugin's logic. These options are injected into the services, subscribers, and APIs of the plugin.
@@ -98,8 +102,8 @@ The following steps will install the official Contentful plugin for your Medusa
First, we add the plugin as a dependency to your project:
```bash
yarn add medusa-plugin-contentful
```bash npm2yarn
npm install medusa-plugin-contentful
```
### Step 2: Configuration

10
docs/content/how-to/create-medusa-app.md
View File

@@ -8,12 +8,16 @@ Starting a new e-commerce project just got easier, now with one command.
## Getting started with `create-medusa-app`
Use `create-medusa-app` with your preferred package manager:
Use `create-medusa-app` with npx:
```bash
npx create-medusa-app
```
Or Yarn:
```bash
yarn create medusa-app
npx create-medusa-app
```
Behind the scenes, `create-medusa-app` is populating your database with some initial set of mock data, which helps to interact with Medusa setup intuitively straight away.

10
docs/content/how-to/deploying-admin-on-netlify.md
View File

@@ -12,7 +12,7 @@ This is a guide for deploying Medusa Admin on Netlify. Netlify is a platform tha
Install Netlify CLI on your machine using npm:
```shell=
```bash npm2yarn
npm install netlify-cli -g
```
@@ -20,7 +20,7 @@ npm install netlify-cli -g
Connect to your Netlify account from your terminal:
```shell=
```bash
netlify login
```
@@ -34,7 +34,7 @@ The Netlify CLI is used to achieve this.
#### Create a new site
```shell=
```bash
netlify init
```
@@ -44,7 +44,7 @@ The default build and deploy settings fit the needs of a Gatsby application, so
#### Add an environment variable
```shell=
```bash
netlify env:set GATSBY_MEDUSA_BACKEND_URL "https://your-medusa-server.com"
```
@@ -54,7 +54,7 @@ The above environment variable should point to your Medusa server.
Finally to deploy the admin, commit and push your changes to the repository connected in step 3.
```shell=
```bash
git add .
git commit -m "Deploy Medusa Admin on Netlify"
git push origin main

12
docs/content/how-to/deploying-gatsby-on-netlify.md
View File

@@ -12,7 +12,7 @@ This is a guide for deploying our [Gatsby storefront starter](https://github.com
Install Netlify CLI on your machine using npm:
```shell=
```bash npm2yarn
npm install netlify-cli -g
```
@@ -20,7 +20,7 @@ npm install netlify-cli -g
Connect to your Netlify account from your terminal:
```shell=
```bash
netlify login
```
@@ -34,7 +34,7 @@ The Netlify CLI is used to achieve this.
#### Create a new site
```shell=
```bash
netlify init
```
@@ -44,8 +44,8 @@ The default build and deploy settings fit the needs of a Gatsby application, so
#### Add an environment variable
```shell=
netlify env:set GATSBY_STORE_URL "https://your-medusa-server.com"
```bash
netlify env:set GATSBY_MEDUSA_BACKEND_URL "https://your-medusa-server.com"
```
The above environment variable should point to your Medusa server.
@@ -54,7 +54,7 @@ The above environment variable should point to your Medusa server.
Finally to deploy the storefront, commit and push your changes to the repository connected in step 3.
```shell=
```bash
git add .
git commit -m "Deploy Medusa Admin on Netlify"
git push origin main

34
docs/content/how-to/deploying-on-heroku.md
View File

@@ -20,13 +20,13 @@ Install Heroku on your machine:
**Ubuntu**
```shell=
```bash
sudo snap install --classic heroku
```
**MacOS**
```shell=
```bash
brew tap heroku/brew && brew install heroku
```
@@ -41,7 +41,7 @@ Download the appropriate installer for your Windows installation:
Connect to your Heroku account from your terminal:
```shell=
```bash
heroku login
```
@@ -51,7 +51,7 @@ heroku login
In your **Medusa project directory** run the following commands to create an app on Heroku and add it as a remote origin.
```shell=
```bash
heroku create medusa-test-app
heroku git:remote -a medusa-test-app
```
@@ -66,7 +66,7 @@ Medusa requires a Postgres database and a Redis instance to work. These are adde
Add a Postgres addon to your Heroku app
```shell=
```bash
heroku addons:create heroku-postgresql:hobby-dev
```
@@ -78,7 +78,7 @@ Add a Redis instance to your Heroku app
> The addon `redistogo:nano` is free, but Heroku requires you to add a payment method to proceed.
```shell=
```bash
heroku addons:create redistogo:nano
```
@@ -88,7 +88,7 @@ You can find more informations, plans and pricing about Redis To Go [here](https
Medusa requires a set of environment variables. From you project repository run the following commands:.
```shell=
```bash
heroku config:set NODE_ENV=production
heroku config:set JWT_SECRET=your-super-secret
heroku config:set COOKIE_SECRET=your-super-secret-pt2
@@ -99,7 +99,7 @@ heroku config:set NPM_CONFIG_PRODUCTION=false
Additionally, we need to set the buildpack to Node.js
```shell=
```bash
heroku buildpacks:set heroku/nodejs
```
@@ -108,25 +108,25 @@ heroku buildpacks:set heroku/nodejs
The library we use for connecting to Redis, does not allow usernames in the connection string. Therefore, we need to perform the following commands to remove it.
Get the current Redis URL:
```shell=
```bash
heroku config:get REDISTOGO_URL
```
You should get something like:
```shell=
```bash
redis://redistogo:some_password_123@some.redistogo.com:9660/
```
Remove the username from the Redis URL:
```shell=
```bash
redis://r̶e̶d̶i̶s̶t̶o̶g̶o̶:some_password_123@sole.redistogo.com:9660/
```
Set the new environment variable `REDIS_URL`
```shell=
```bash
heroku config:set REDIS_URL=redis://:some_password_123@sole.redistogo.com:9660/
```
@@ -138,7 +138,7 @@ Before jumping into the deployment, we need to configure Medusa.
Update `module.exports` to include the following:
```javascript=
```js
module.exports = {
projectConfig: {
redis_url: REDIS_URL,
@@ -159,7 +159,7 @@ module.exports = {
Update `scripts` to include the following:
```json=
```json
...
"scripts": {
"serve": "medusa start",
@@ -175,7 +175,7 @@ Update `scripts` to include the following:
Finally, we need to commit and push our changes to Heroku:
```shell=
```bash
git add .
git commit -m "Deploy Medusa App on Heroku"
git push heroku HEAD:master
@@ -185,7 +185,7 @@ git push heroku HEAD:master
You can explore your Heroku app build logs using the following command in your project directory.
```shell=
```bash
heroku logs -n 500000 --remote heroku --tail
```
@@ -193,7 +193,7 @@ heroku logs -n 500000 --remote heroku --tail
As an optional extra step, we can create a user for you to use when your admin system is up and running.
```shell=
```bash
heroku run -a medusa-test-app -- medusa user -e "some-user@test.com" -p "SuperSecret1234"
```

12
docs/content/how-to/deploying-on-qovery.md
View File

@@ -33,21 +33,21 @@ Our Medusa project needs a bit of configuration to fit the needs of Qovery.
First, add the Postgres and Redis database url to your `medusa-config.js`. In Qovery, click on your Medusa app in the environment overview. Navigate to environment variables in the sidebar on the left. Among the secret variables you should find your database urls. They should look something like this:
```javascript=
```bash
QOVERY_REDIS_123456789_DATABASE_URL
QOVERY_POSTGRESQL_123456789_DATABASE_URL
```
Add these to your `medusa-config.js`.
```javascript=
```js
const DATABASE_URL = process.env.QOVERY_POSTGRESQL_123456789_DATABASE_URL
const REDIS_URL= process.env.QOVERY_REDIS_123456789_DATABASE_URL
```
Furthermore, update `module.exports` to include the following:
```javascript=
```js
module.exports = {
projectConfig: {
redis_url: REDIS_URL,
@@ -70,7 +70,7 @@ module.exports = {
We need to add a couple of more environment variables in Qovery. Add the following variables in your Console with an application scope:
```javascript=
```bash
JTW_SECRET=something_secret_jwt
COOKIE_SECRET=something_secret_cookie
```
@@ -81,7 +81,7 @@ COOKIE_SECRET=something_secret_cookie
Update `scripts` to the following:
```json=
```json
"scripts": {
"serve": "medusa start",
"start": "medusa migrations run && medusa start",
@@ -102,7 +102,7 @@ In your environment overview in Qovery, deploy your databases one after the othe
To initialise your first build Qovery, simply commit and push your changes.
```shell=
```bash
git add .
git commit -m "chore: Qovery setup"
git push origin main

46
docs/content/how-to/headless-ecommerce-store-with-gatsby-contentful-medusa.md
View File

@@ -38,17 +38,20 @@ If you want to jump straight to the code for this series you can checkout:
In order to get you started with your Gatsby, Contentful, Medusa store you must complete a couple of installations:
- Install the Medusa CLI
```bash npm2yarn
npm install @medusajs/medusa-cli -g
```
yarn global add @medusajs/medusa-cli
npm install -g @medusajs/medusa-cli
```
- Install the Gatsby CLI
```bash npm2yarn
npm install gatsby-cli -g
```
yarn global add gatsby-cli
npm install -g gatsby-cli
```
- [Create a Contentful account](https://www.contentful.com/sign-up/)
- [Install Redis](https://redis.io/topics/quickstart)
```
brew install redis
brew services start redis
@@ -60,7 +63,7 @@ Medusa has support for SQLite and PostgreSQL and uses Redis for caching and queu
We will make use of `medusa new` to setup your local Medusa server.
```sh
```bash
medusa new medusa-contentful-store https://github.com/medusajs/medusa-starter-contentful
```
@@ -146,7 +149,14 @@ In the `/src` directory there are 4 special subdirectories that are added for yo
#### `/data`
We will be using two seed scripts to kickstart your development, namely `yarn seed:contentful` and `yarn seed`. Data for these seed scripts are contained in the `/data` directory.
We will be using two seed scripts to kickstart your development, namely:
```bash npm2yarn
npm run seed:contentful
npm run seed
```
Data for these seed scripts are contained in the `/data` directory.
When the seed scripts have been executed you will have a Contentful space that holds all the data for your website; this includes content for Pages, Navigtion Menu, etc.
@@ -229,8 +239,8 @@ Now that we have collected your credentials we are ready to migrate the Contentf
You can now run:
```shell
yarn migrate:contentful
```bash npm2yarn
npm run migrate:contentful
```
This script will run each of the migrations in the `contentful-migrations` directory. After it has completed navigate to your Contentful space and click "Content model" in the top navigation bar. You will see that the content types will be imported into your space. Feel free to familiarize yourself with the different types by clicking them and inspecting the different fields that they hold.
@@ -239,8 +249,8 @@ This script will run each of the migrations in the `contentful-migrations` direc
The next step is to seed the Contentful space with some data that can be used to display your ecommerce store's pages and navigation. To seed the database open up your command line and run:
```shell
yarn seed:contentful
```bash npm2yarn
npm run seed:contentful
```
In your Contentful space navigate to "Content" and you will be able to see the different entries in your space. You can filter the entries by type to, for example, only view Pages:
@@ -251,9 +261,9 @@ You will notice that there are not any Products in your store yet and this is be
To do this open your command line and run:
```shell
yarn seed
yarn start
```bash npm2yarn
npm run seed
npm run start
```
This will seed your Medusa database, which will result in `medusa-plugin-contentful` synchronizing data to your Contentful space. Everytime you add or update a product the data will be copied into your Contentful space for further enrichment.
@@ -289,7 +299,11 @@ Once `gatsby new` is complete you should rename the `.env.template` file to `.en
To get your token go to **Settings** > **API Keys** > **Add API key**. Now click save and copy the token specified in the field "Content Delivery API - access token".
After you have copied the token and your space ID to your `.env`, you can run `yarn start` which will start your Gatsby development server on port 8000.
After you have copied the token and your space ID to your `.env`, you can start your Gatsby development server on port 8000 by running:
```bash npm2yarn
npm run start
```
You can now go to https://localhost:8000 to check out your new Medusa store.

12
docs/content/how-to/making-your-store-more-powerful-with-contentful.md
View File

@@ -39,8 +39,8 @@ module.exports = function (migration, context) {
This small snippet will create a content model in your Contentful space with two fields: a title which will be used to name entries in a meaningful manner (i.e. it won't be displayed to customers) and a body which contains the rich text to display. To apply your migration run:
```shell
yarn migrate:contentful --file contentful-migrations/rich-text.js
```bash npm2yarn
npm run migrate:contentful --file contentful-migrations/rich-text.js
```
If you go to your Contentful space and click Content Model you will see that the Rich Text model has been added to your space:
@@ -68,8 +68,8 @@ module.exports = function (migration, context) {
After migrating your space you are ready create your new contact page:
```shell
yarn migrate:contentful --file contentful-migrations/update-page-module-validation.js
```bash npm2yarn
npm run migrate:contentful --file contentful-migrations/update-page-module-validation.js
```
## Adding Rich Text to About
@@ -197,8 +197,8 @@ module.exports = function (migration, context) {
Run the migration:
```
yarn migrate:contentful --file contentful-migrations/product-add-modules.js
```bash npm2yarn
npm run migrate:contentful --file contentful-migrations/product-add-modules.js
```
### Adding "Related Products" Tile Section

4
docs/content/how-to/uploading-images-to-minio.md
View File

@@ -26,8 +26,8 @@ Navigate to users and perform the following steps:
First, install the plugin using your preferred package manager:
```
yarn add medusa-file-minio
```bash npm2yarn
npm install medusa-file-minio
```
Then configure your `medusa-config.js` to include the plugin alongside the required options:

4
docs/content/how-to/uploading-images-to-s3.md
View File

@@ -51,8 +51,8 @@ Upon successful creation of the user, you are presented with an **Access key ID*
First, install the plugin using your preferred package manager:
```
yarn add medusa-file-s3
```bash npm2yarn
npm install medusa-file-s3
```
Then configure your `medusa-config.js` to include the plugin alongside the required options:

4
docs/content/how-to/uploading-images-to-spaces.md
View File

@@ -20,8 +20,8 @@ Navigate to API in the left sidebar. Generate a new Spaces access key. This shou
First, install the plugin using your preferred package manager:
```
yarn add medusa-file-spaces
```bash npm2yarn
npm install medusa-file-spaces
```
Then configure your `medusa-config.js` to include the plugin alongside the required options:

23
docs/content/quickstart/quick-start.md
View File

@@ -1,22 +1,39 @@
# Quickstart
This quickstart is intended for experienced developers, that are accustomed with concepts like JavaScript, Node.js, SQL and the command line. For a more gentle introduction, see our tutorial on [how to set up your development environment](https://docs.medusajs.com/tutorial/set-up-your-development-environment).
This quickstart is intended for experienced developers, that are accustomed with concepts like JavaScript, Node.js, SQL and the command line. For a more gentle introduction, see our tutorial on [how to set up your development environment](../tutorial/0-set-up-your-development-environment.md).
## Prerequisites
Medusa supports Node versions 14 and 16. You can check which version of Node you have by running the following command:
```bash
node -v
```
You can install Node from the [official website](https://nodejs.org/en/).
## Getting started
1. **Install Medusa CLI**
```bash
```bash npm2yarn
npm install -g @medusajs/medusa-cli
```
2. **Create a new Medusa project**
```
```bash
medusa new my-medusa-store --seed
```
3. **Start your Medusa engine**
```bash
medusa develop
```
4. **Use the API**
```bash
curl localhost:9000/store/products | python -m json.tool
```

8
docs/content/starters/gatsby-medusa-starter.md
View File

@@ -16,17 +16,15 @@ mv .env.template .env.development
**Install dependencies**
Use your favourite package manager to install dependencies:
```shell
yarn
# or
```bash npm2yarn
npm install
```
**Start developing.**
Start up the local server:
```shell
yarn start
```bash npm2yarn
npm run start
```
Your site is now running at http://localhost:8000!

8
docs/content/starters/nextjs-medusa-starter.md
View File

@@ -16,17 +16,15 @@ mv .env.template .env.local
**Install dependencies**
Use your favourite package manager to install dependencies:
```shell
yarn
# or
```bash npm2yarn
npm install
```
**Start developing.**
Start up the local server:
```shell
yarn dev
```bash npm2yarn
npm run dev
```
Your site is now running at http://localhost:8000!

7
docs/content/troubleshooting/documentation-error.md Normal file
View File

@@ -0,0 +1,7 @@
# Documentation Error
If you have installed the dependencies in the root of this repository (i.e., if you have a `node_modules` directory at the root of this repository), this will cause an error when running this documentation website. This is because the content resides in `docs/content` and when that content is being imported from there, a mix up can happen between the dependencies which will cause an `invalid hook call` error.
For that reason, we added a `clean-node-modules` script that deletes the `node_modules` directory, and we call that script before the `start` and `build` scripts are ran.
So, everytime you run these 2 scripts, the `node_modules` directory at the root will be deleted.

4
docs/content/troubleshooting/missing-payment-providers.md
View File

@@ -19,9 +19,7 @@ const plugins = [
And installing them through your favourite package manager:
```bash
yarn add medusa-payment-stripe
# or
```bash npm2yarn
npm install medusa-payment-stripe
```

6
docs/content/troubleshooting/transaction-error-in-checkout.md
View File

@@ -34,4 +34,8 @@ module.exports = {
}
```
> When changing from SQLite to Postgres, you should seed the database again using: `yarn seed`
> When changing from SQLite to Postgres, you should seed the database again using:
```bash npm2yarn
npm run seed
```

20
docs/content/tutorial/0-set-up-your-development-environment.md
View File

@@ -42,6 +42,16 @@ Node.js is an environment that can execute JavaScript code on outside of the bro
Node.js has a bundled package manager called npm. npm helps you install "packages" which are small pieces of code that you can leverage in your Node.js applications. Medusa's core is itself a package distributed via npm and so are all of the plugins that exist around the core. [You can install Node.js from here.](https://nodejs.org/en/)
:::caution
Medusa supports Node versions 14 and 16. You can check which Node version you have using the following command:
```bash
node -v
```
:::
If you prefer using something like homebrew you can also run:
```
@@ -87,14 +97,8 @@ brew services start redis
The final installation to do to get started with Medusa is the Medusa CLI, which is an npm package you can install globally on your computer to get instant access to commands that help you manage and run your Medusa project. As the Medusa CLI is distributed as an npm package it is very easily installed by running:
```
npm install -g @medusajs/medusa-cli
```
We like to use Yarn instead of npm; if you wish to do the same you can install the CLI with:
```
yarn global add @medusajs/medusa-cli
```bash npm2yarn
npm install @medusajs/medusa-cli -g
```
### Text editor

2
docs/content/tutorial/2-adding-custom-functionality.md
View File

@@ -16,7 +16,7 @@ The custom functionality will do a number of things:
## Services
We will begin our custom implementation by adding a custom service. In you project create a new file at `/src/services/welcome.js`. Open the newly created file and add a class:
We will begin our custom implementation by adding a custom service. In your project create a new file at `/src/services/welcome.js`. Open the newly created file and add a class:
```javascript
import { BaseService } from "medusa-interfaces"

8
www/docs/README.md
View File

@@ -1,3 +1,11 @@
# Website
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
## Note Before Development
If you have installed the dependencies in the root of this repository (i.e., if you have a `node_modules` directory at the root of this repository), this will cause an error when running this documentation website. This is because the content resides in `docs/content` and when that content is being imported from there, a mix up can happen between the dependencies which will cause an `invalid hook call` error.
For that reason, we added a `clean-node-modules` script that deletes the `node_modules` directory, and we call that script before the `start` and `build` scripts are ran.
So, everytime you run these 2 scripts, the `node_modules` directory at the root will be deleted.

26
www/docs/docusaurus.config.js
View File

@@ -6,7 +6,7 @@ const algoliaApiKey = process.env.ALGOLIA_API_KEY || "temp"
/** @type {import('@docusaurus/types').DocusaurusConfig} */
module.exports = {
title: "Medusa Commerce",
title: "Medusa",
tagline: "Explore and learn how to use Medusa",
url: "https://docs.medusajs.com",
baseUrl: "/",
@@ -25,18 +25,22 @@ module.exports = {
],
],
themeConfig: {
disableSwitch: true,
colorMode: {
defaultMode: 'light',
disableSwitch: true,
},
algolia: {
apiKey: algoliaApiKey,
indexName: "medusa-commerce",
placeholder: "Search docs...",
appId: algoliaAppId,
contextualSearch: false,
},
prism: {
defaultLanguage: "js",
plugins: ["line-numbers", "show-language"],
theme: require("@kiwicopple/prism-react-renderer/themes/vsDark"),
darkTheme: require("@kiwicopple/prism-react-renderer/themes/vsDark"),
theme: require("prism-react-renderer/themes/vsDark"),
darkTheme: require("prism-react-renderer/themes/vsDark"),
},
navbar: {
hideOnScroll: true,
@@ -44,6 +48,7 @@ module.exports = {
alt: "Medusa Commerce",
src: "img/logo.svg",
srcDark: "img/logo.svg",
width: 100
},
items: [
{
@@ -98,12 +103,12 @@ module.exports = {
title: "More",
items: [
{
label: "Contact",
href: "https://medusa-commere.com",
label: "Medusa Home",
href: "https://medusajs.com",
},
{
label: "Privacy & Terms",
href: "https://medusa-commere.com",
label: "Contact",
href: "https://ky5eo2x1u81.typeform.com/get-in-touch",
},
{
label: "GitHub",
@@ -112,7 +117,7 @@ module.exports = {
],
},
],
copyright: `© ${new Date().getFullYear()} Medusa Commerce`,
copyright: `© ${new Date().getFullYear()} Medusa`,
},
},
presets: [
@@ -124,6 +129,9 @@ module.exports = {
editUrl: "https://github.com/medusajs/medusa/edit/master/www/",
path: docsPath,
routeBasePath: "/",
remarkPlugins: [
[require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
],
},
theme: {
customCss: require.resolve("./src/css/custom.css"),

18
www/docs/package.json
View File

@@ -4,7 +4,10 @@
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"clean-node-modules": "rm -rf ../../node_modules",
"prestart": "yarn clean-node-modules",
"start": "docusaurus clear && docusaurus start",
"prebuild": "yarn clean-node-modules",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
@@ -14,17 +17,16 @@
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "2.0.0-beta.3",
"@docusaurus/preset-classic": "2.0.0-beta.3",
"@docusaurus/theme-search-algolia": "^2.0.0-beta.3",
"@kiwicopple/prism-react-renderer": "github:kiwicopple/prism-react-renderer",
"@mdx-js/react": "^1.6.21",
"@svgr/webpack": "^5.5.0",
"@docusaurus/core": "2.0.0-beta.17",
"@docusaurus/preset-classic": "2.0.0-beta.17",
"@docusaurus/remark-plugin-npm2yarn": "^2.0.0-beta.18",
"@svgr/webpack": "6.2.1",
"algoliasearch-helper": "^3.8.2",
"clsx": "^1.1.1",
"docusaurus2-dotenv": "^1.4.0",
"file-loader": "^6.2.0",
"lodash": "^4.17.21",
"prism-react-renderer": "^1.2.1",
"prism-react-renderer": "^1.3.1",
"react": "^17.0.1",
"react-dom": "^17.0.1",
"url-loader": "^4.1.1"
@@ -44,4 +46,4 @@
"devDependencies": {
"prettier": "^2.3.2"
}
}
}

234
www/docs/sidebars.js
View File

@@ -63,6 +63,10 @@ module.exports = {
},
],
},
{
type: "doc",
id: "admin/quickstart",
},
{
type: "doc",
id: "how-to/create-medusa-app",
@@ -130,7 +134,7 @@ module.exports = {
{
type: "category",
label: 'Services',
collapsed: true,
collapsed: false,
items: [
{
type: "doc",
@@ -139,6 +143,55 @@ module.exports = {
},
]
},
{
type: "category",
label: 'Subscribers',
collapsed: false,
items: [
{
type: "doc",
id: "advanced/backend/subscribers/create-subscriber",
label: "Create a Subscriber"
},
]
},
{
type: "category",
label: 'Shipping',
collapsed: true,
items: [
{
type: "doc",
id: "advanced/backend/shipping/overview",
label: "Architecture Overview"
},
{
type: "doc",
id: "advanced/backend/shipping/add-fulfillment-provider",
label: "Add Fulfillment Provider"
}
]
},
{
type: "category",
label: 'Payment',
collapsed: true,
items: [
{
type: "doc",
id: "advanced/backend/payment/overview",
label: "Architecture Overview"
},
{
type: "doc",
id: "advanced/backend/payment/how-to-create-payment-provider",
},
{
type: "doc",
id: "advanced/backend/payment/frontend-payment-flow-in-checkout",
},
]
},
{
type: "doc",
id: "tutorial/adding-custom-functionality",
@@ -156,10 +209,6 @@ module.exports = {
type: "doc",
id: "guides/plugins",
},
{
type: "doc",
id: "guides/checkouts",
},
{
type: "doc",
id: "guides/carts-in-medusa",
@@ -175,82 +224,134 @@ module.exports = {
items: [
{
type: "category",
label: "Gatsby + Contentful + Medusa",
label: "Analytics",
items: [
{
type: "doc",
id: "how-to/headless-ecommerce-store-with-gatsby-contentful-medusa",
},
{
type: "doc",
id: "how-to/making-your-store-more-powerful-with-contentful",
id: "add-plugins/segment",
label: "Segment",
},
],
},
{
type: "doc",
id: "add-plugins/contentful",
label: "CMS: Contentful",
type: "category",
label: "Bot",
items: [
{
type: "doc",
id: "add-plugins/slack",
label: "Slack",
},
],
},
{
type: "doc",
id: "add-plugins/strapi",
label: "CMS: Strapi",
type: "category",
label: "CMS",
items: [
{
type: "doc",
id: "add-plugins/contentful",
label: "Contentful",
},
{
type: "doc",
id: "add-plugins/strapi",
label: "Strapi",
},
{
type: "category",
label: "Gatsby + Contentful + Medusa",
items: [
{
type: "doc",
id: "how-to/headless-ecommerce-store-with-gatsby-contentful-medusa",
},
{
type: "doc",
id: "how-to/making-your-store-more-powerful-with-contentful",
},
],
},
],
},
{
type: "doc",
id: "add-plugins/segment",
label: "Analytics: Segment",
type: "category",
label: "Notifications",
items: [
{
type: "doc",
id: "add-plugins/sendgrid",
label: "SendGrid",
},
{
type: "doc",
id: "add-plugins/mailchimp",
label: "Mailchimp",
},
{
type: "doc",
id: "add-plugins/twilio-sms",
label: "Twilio SMS",
},
],
},
{
type: "doc",
id: "add-plugins/meilisearch",
label: "Search: MeiliSearch",
type: "category",
label: "Payment",
items: [
{
type: "doc",
id: "add-plugins/klarna",
label: "Klarna",
},
{
type: "doc",
id: "add-plugins/paypal",
label: "PayPal",
},
{
type: "doc",
id: "add-plugins/stripe",
label: "Stripe",
},
],
},
{
type: "doc",
id: "add-plugins/algolia",
label: "Search: Algolia",
type: "category",
label: "Search",
items: [
{
type: "doc",
id: "add-plugins/algolia",
label: "Algolia",
},
{
type: "doc",
id: "add-plugins/meilisearch",
label: "MeiliSearch",
},
],
},
{
type: "doc",
id: "add-plugins/spaces",
label: "File: Spaces",
},
{
type: "doc",
id: "add-plugins/s3",
label: "File: S3",
},
{
type: "doc",
id: "add-plugins/minio",
label: "File: MinIO",
},
{
type: "doc",
id: "add-plugins/stripe",
label: "Payment: Stripe",
},
{
type: "doc",
id: "add-plugins/klarna",
label: "Payment: Klarna",
},
{
type: "doc",
id: "add-plugins/paypal",
label: "Payment: PayPal",
},
{
type: "doc",
id: "add-plugins/sendgrid",
label: "Notification: SendGrid",
},
{
type: "doc",
id: "add-plugins/slack",
label: "Bot: Slack",
type: "category",
label: "Storage",
items: [
{
type: "doc",
id: "add-plugins/minio",
label: "MinIO",
},
{
type: "doc",
id: "add-plugins/s3",
label: "S3",
},
{
type: "doc",
id: "add-plugins/spaces",
label: "Spaces",
},
],
},
],
},
@@ -283,6 +384,11 @@ module.exports = {
id: "troubleshooting/signing-in-to-admin",
label: "Signing in to Medusa Admin",
},
{
type: "doc",
id: "troubleshooting/documentation-error",
label: "Documentation Error",
},
],
},
],

9
www/docs/src/components/Banner/Banner.js
View File

@@ -1,13 +1,14 @@
import React, { useEffect, useState } from "react"
import CloseIcon from "../close-icon"
import styles from "./banner.module.css"
import clsx from "clsx"
import useThemeContext from "@theme/hooks/useThemeContext"
import ConfLogo from "../../../static/img/logo.svg"
import clsx from "clsx"
import styles from "./banner.module.css"
import {useColorMode} from '@docusaurus/theme-common';
const Banner = (props) => {
const [isBannerVisible, setIsBannerVisible] = useState(true)
const { isDarkTheme } = useThemeContext()
const { isDarkTheme } = useColorMode()
const handleDismissBanner = () => {
setIsBannerVisible(false)

35
www/docs/src/css/custom.css
View File

@@ -62,12 +62,19 @@ p {
/* DocSearch */
html[data-theme="light"] .DocSearch-Button {
/* html[data-theme="light"] .DocSearch-Button {
--docsearch-searchbox-background: #fff;
}
html[data-theme="dark"] .DocSearch-Button {
--docsearch-searchbox-background: #1f1f1f;
} */
.DocSearch-Button {
width: 100%;
max-width: 175px;
border-radius: 8px !important;
--docsearch-container-background: #f5f6f7;
}
span.DocSearch-Button-Key {
@@ -90,11 +97,6 @@ html[data-theme="dark"] .docusaurus-highlight-code-line {
font-size: 14px;
}
/* Medusa logo */
.navbar__brand {
width: 100px;
}
.navbar-github-link:before {
content: "";
width: 24px;
@@ -203,10 +205,6 @@ footer .footer__items svg {
display: none;
}
footer .footer__item a:hover {
color: white;
}
@media screen and (min-width: 966px) {
footer .footer__col {
display: flex;
@@ -255,3 +253,20 @@ footer {
.prism-code div:active {
outline: none !important;
}
details summary {
cursor: pointer;
}
.theme-doc-markdown a {
color: #9461ff;
}
.theme-doc-markdown a:hover {
color: #6e3eff;
text-decoration: none;
}
.DocSearch-Container {
z-index: 1001 !important;
}

249
www/docs/src/theme/SearchBar/index.js
View File

@@ -1,249 +1,10 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import { DocSearchButton, useDocSearchKeyboardEvents } from "@docsearch/react"
import Head from "@docusaurus/Head"
import Link from "@docusaurus/Link"
import { useHistory } from "@docusaurus/router"
import { translate } from "@docusaurus/Translate"
import { useBaseUrlUtils } from "@docusaurus/useBaseUrl"
import useDocusaurusContext from "@docusaurus/useDocusaurusContext"
import useAlgoliaContextualFacetFilters from "@theme/hooks/useAlgoliaContextualFacetFilters"
import useSearchQuery from "@theme/hooks/useSearchQuery"
import React, { useCallback, useMemo, useRef, useState } from "react"
import { createPortal } from "react-dom"
import styles from "./styles.module.css"
let DocSearchModal = null
const convertToKebabCase = (string) => {
return string
.replace(/\s+/g, "-")
.replace("'", "")
.replace(".", "")
.replace('"', "")
.toLowerCase()
}
const replaceUrl = (item) => {
let { url, hierarchy } = item
if (url.includes("api/store") || url.includes("/api/admin")) {
url = url.replace("#", "")
if (hierarchy.lvl2) {
const index = url.lastIndexOf("/")
url =
url.substring(0, index) +
`/${convertToKebabCase(hierarchy.lvl1)}` +
url.substring(index)
}
}
return url
}
function Hit({ hit, children }) {
if (hit.url.includes("/api/store") || hit.url.includes("/api/admin")) {
const url = replaceUrl(hit)
return <a href={url}>{children}</a>
}
return <Link to={hit.url}>{children}</Link>
}
function ResultsFooter({ state, onClose }) {
const { generateSearchPageLink } = useSearchQuery()
return (
<Link to={generateSearchPageLink(state.query)} onClick={onClose}>
See all {state.context.nbHits} results
</Link>
)
}
function DocSearch({ contextualSearch, ...props }) {
const { siteMetadata } = useDocusaurusContext()
const contextualSearchFacetFilters = useAlgoliaContextualFacetFilters()
const configFacetFilters = props.searchParameters?.facetFilters ?? []
const facetFilters = contextualSearch
? // Merge contextual search filters with config filters
[...contextualSearchFacetFilters, ...configFacetFilters]
: // ... or use config facetFilters
configFacetFilters
// we let user override default searchParameters if he wants to
const searchParameters = {
...props.searchParameters,
facetFilters,
}
const { withBaseUrl } = useBaseUrlUtils()
const history = useHistory()
const searchContainer = useRef(null)
const searchButtonRef = useRef(null)
const [isOpen, setIsOpen] = useState(false)
const [initialQuery, setInitialQuery] = useState(null)
const importDocSearchModalIfNeeded = useCallback(() => {
if (DocSearchModal) {
return Promise.resolve()
}
return Promise.all([
import("@docsearch/react/modal"),
import("@docsearch/react/style"),
import("./styles.css"),
]).then(([{ DocSearchModal: Modal }]) => {
DocSearchModal = Modal
})
}, [])
const onOpen = useCallback(() => {
importDocSearchModalIfNeeded().then(() => {
searchContainer.current = document.createElement("div")
document.body.insertBefore(
searchContainer.current,
document.body.firstChild
)
setIsOpen(true)
})
}, [importDocSearchModalIfNeeded, setIsOpen])
const onClose = useCallback(() => {
setIsOpen(false)
searchContainer.current.remove()
}, [setIsOpen])
const onInput = useCallback(
(event) => {
importDocSearchModalIfNeeded().then(() => {
setIsOpen(true)
setInitialQuery(event.key)
})
},
[importDocSearchModalIfNeeded, setIsOpen, setInitialQuery]
)
const navigator = useRef({
navigate({ item }) {
const url = replaceUrl(item)
// Need to type out the entire URL to prevent it from attempting to open the page
// as part of the docusaurus project. Which will fail.
window.location = `https://docs.medusajs.com${url}`
},
navigateNewTab({ item }) {
const url = replaceUrl(item)
const windowReference = window.open(url, "_blank", "noopener")
if (windowReference) {
windowReference.focus()
}
},
navigateNewWindow({ item }) {
const url = replaceUrl(item)
window.open(url, "_blank", "noopener")
},
}).current
const transformItems = useRef((items) => {
return items.map((item) => {
// We transform the absolute URL into a relative URL.
// Alternatively, we can use `new URL(item.url)` but it's not
// supported in IE.
const a = document.createElement("a")
a.href = item.url
return {
...item,
url: withBaseUrl(`${a.pathname}${a.hash}`),
}
})
}).current
const resultsFooterComponent = useMemo(
() => (footerProps) => <ResultsFooter {...footerProps} onClose={onClose} />,
[onClose]
)
const transformSearchClient = useCallback(
(searchClient) => {
searchClient.addAlgoliaAgent("docusaurus", siteMetadata.docusaurusVersion)
return searchClient
},
[siteMetadata.docusaurusVersion]
)
useDocSearchKeyboardEvents({
isOpen,
onOpen,
onClose,
onInput,
searchButtonRef,
})
const translatedSearchLabel = translate({
id: "theme.SearchBar.label",
message: "Search",
description: "The ARIA label and placeholder for search button",
})
import React from 'react';
import SearchBar from '@theme-original/SearchBar';
export default function SearchBarWrapper(props) {
return (
<>
<Head>
{/* This hints the browser that the website will load data from Algolia,
and allows it to preconnect to the DocSearch cluster. It makes the first
query faster, especially on mobile. */}
<link
rel="preconnect"
href={`https://${props.appId}-dsn.algolia.net`}
crossOrigin="anonymous"
/>
</Head>
<div className={styles.searchBox}>
<DocSearchButton
onTouchStart={importDocSearchModalIfNeeded}
onFocus={importDocSearchModalIfNeeded}
onMouseOver={importDocSearchModalIfNeeded}
onClick={onOpen}
ref={searchButtonRef}
translations={{
buttonText: translatedSearchLabel,
buttonAriaLabel: translatedSearchLabel,
}}
/>
</div>
{isOpen &&
createPortal(
<DocSearchModal
onClose={onClose}
initialScrollY={window.scrollY}
initialQuery={initialQuery}
navigator={navigator}
transformItems={transformItems}
hitComponent={Hit}
resultsFooterComponent={resultsFooterComponent}
transformSearchClient={transformSearchClient}
{...props}
searchParameters={searchParameters}
/>,
searchContainer.current
)}
<SearchBar {...props} />
</>
)
);
}
function SearchBar() {
const { siteConfig } = useDocusaurusContext()
return <DocSearch {...siteConfig.themeConfig.algolia} />
}
export default SearchBar

8
www/docs/src/theme/SearchPage/index.d.ts vendored Normal file
View File

@@ -0,0 +1,8 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
/// <reference types="react" />
export default function SearchPage(): JSX.Element;

447
www/docs/src/theme/SearchPage/index.js Normal file
View File

File diff suppressed because one or more lines are too long

119
www/docs/src/theme/SearchPage/styles.module.css Normal file
View File

@@ -0,0 +1,119 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
.searchQueryInput,
.searchVersionInput {
border-radius: var(--ifm-global-radius);
border: 2px solid var(--ifm-toc-border-color);
font: var(--ifm-font-size-base) var(--ifm-font-family-base);
padding: 0.8rem;
width: 100%;
background: var(--docsearch-searchbox-focus-background);
color: var(--docsearch-text-color);
margin-bottom: 0.5rem;
transition: border var(--ifm-transition-fast) ease;
}
.searchQueryInput:focus,
.searchVersionInput:focus {
border-color: var(--docsearch-primary-color);
outline: none;
}
.searchQueryInput::placeholder {
color: var(--docsearch-muted-color);
}
.searchResultsColumn {
font-size: 0.9rem;
font-weight: bold;
}
.algoliaLogo {
max-width: 150px;
}
.algoliaLogoPathFill {
fill: var(--ifm-font-color-base);
}
.searchResultItem {
padding: 1rem 0;
border-bottom: 1px solid var(--ifm-toc-border-color);
}
.searchResultItemHeading {
font-weight: 400;
margin-bottom: 0;
}
.searchResultItemPath {
font-size: 0.8rem;
color: var(--ifm-color-content-secondary);
--ifm-breadcrumb-separator-size-multiplier: 1;
}
.searchResultItemSummary {
margin: 0.5rem 0 0;
font-style: italic;
}
@media only screen and (max-width: 996px) {
.searchQueryColumn {
max-width: 60% !important;
}
.searchVersionColumn {
max-width: 40% !important;
}
.searchResultsColumn {
max-width: 60% !important;
}
.searchLogoColumn {
max-width: 40% !important;
padding-left: 0 !important;
}
}
@media screen and (max-width: 576px) {
.searchQueryColumn {
max-width: 100% !important;
}
.searchVersionColumn {
max-width: 100% !important;
padding-left: var(--ifm-spacing-horizontal) !important;
}
}
.loadingSpinner {
width: 3rem;
height: 3rem;
border: 0.4em solid #eee;
border-top-color: var(--ifm-color-primary);
border-radius: 50%;
animation: loading-spin 1s linear infinite;
margin: 0 auto;
}
@keyframes loading-spin {
100% {
transform: rotate(360deg);
}
}
.loader {
margin-top: 2rem;
}
:global(.search-result-match) {
color: var(--docsearch-hit-color);
background: rgb(255 215 142 / 25%);
padding: 0.09em 0;
}

19
www/docs/src/theme/Tabs/index.js Normal file
View File

@@ -0,0 +1,19 @@
import React, { useEffect } from 'react';
import Tabs from '@theme-original/Tabs';
export default function TabsWrapper(props) {
useEffect(() => {
if (!window.localStorage.getItem('docusaurus.tab.npm2yarn')) {
//set the default
window.localStorage.setItem('docusaurus.tab.npm2yarn', 'yarn')
}
}, [])
return (
<>
<Tabs {...props} />
</>
);
}

3896
www/docs/yarn.lock
View File

File diff suppressed because it is too large Load Diff

4
www/reference/gatsby-node.js
View File

@@ -331,7 +331,7 @@ const createAllPages = (sections, api, siteData, createPage, template) => {
api: api,
title: edge.section.section_name,
description: edge.section.schema ? edge.section.schema.description : "",
to: { section: baseURL, method: null },
to: { section: baseURL, method: null, sectionObj: edge.section },
},
})
edge.section.paths.forEach(p => {
@@ -345,7 +345,7 @@ const createAllPages = (sections, api, siteData, createPage, template) => {
api: api,
title: method.summary,
description: method.description || "",
to: { section: baseURL, method: methodURL },
to: { section: baseURL, method: methodURL, sectionObj: edge.section },
},
})
})

15
www/reference/src/components/content/index.js
View File

@@ -1,9 +1,10 @@
import React from "react"
import { Box, Flex } from "theme-ui"
import Topbar from "../topbar"
import Section from "./section"
const Content = ({ data, api }) => {
import React from "react"
import Section from "./section"
import Topbar from "../topbar"
const Content = ({ data, currentSection, api }) => {
return (
<Flex
sx={{
@@ -20,11 +21,7 @@ const Content = ({ data, api }) => {
},
}}
>
<main className="DocSearch-content">
{data.sections.map((s, i) => {
return <Section key={i} data={s} api={api} />
})}
</main>
<Section data={currentSection} api={api} />
</Box>
</Flex>
)

4
www/reference/src/components/content/method.js
View File

@@ -13,7 +13,7 @@ import { formatMethodParams } from "../../utils/format-parameters"
import { formatRoute } from "../../utils/format-route"
import useInView from "../../hooks/use-in-view"
const Method = ({ data, section, pathname, api }) => {
const Method = ({ data, section, sectionData, pathname, api }) => {
const { parameters, requestBody, description, method, summary } = data
const jsonResponse = data.responses[0].content?.[0].json
const { updateHash, updateMetadata } = useContext(NavigationContext)
@@ -27,7 +27,7 @@ const Method = ({ data, section, pathname, api }) => {
useEffect(() => {
if (isInView) {
updateHash(section, convertToKebabCase(summary))
updateHash(section, convertToKebabCase(summary), sectionData)
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [isInView])

36
www/reference/src/components/content/section.js
View File

@@ -1,21 +1,22 @@
import React, { useState, useRef, useEffect, useContext } from "react"
import { Flex, Box, Heading, Text, Button } from "theme-ui"
import Method from "./method"
import Parameters from "./parameters"
import { convertToKebabCase } from "../../utils/convert-to-kebab-case"
import EndpointContainer from "./endpoint-container"
import Markdown from "react-markdown"
import JsonContainer from "./json-container"
import ResponsiveContainer from "./responsive-container"
import Description from "./description"
import NavigationContext from "../../context/navigation-context"
import { Box, Button, Flex, Heading, Text } from "theme-ui"
import React, { useContext, useEffect, useRef, useState } from "react"
import ChevronDown from "../icons/chevron-down"
import Description from "./description"
import EndpointContainer from "./endpoint-container"
import JsonContainer from "./json-container"
import Markdown from "react-markdown"
import Method from "./method"
import NavigationContext from "../../context/navigation-context"
import Parameters from "./parameters"
import ResponsiveContainer from "./responsive-container"
import { convertToKebabCase } from "../../utils/convert-to-kebab-case"
import useInView from "../../hooks/use-in-view"
const Section = ({ data, api }) => {
const { section } = data
const section = data;
const [isExpanded, setIsExpanded] = useState(false)
const { openSections, updateSection, updateMetadata } = useContext(
const { openSections, updateSection, updateMetadata, updateHash } = useContext(
NavigationContext
)
@@ -61,6 +62,12 @@ const Section = ({ data, api }) => {
}
}, [section.section_name, openSections, openSections.length])
useEffect(() => {
if (section.section_name) {
updateHash(convertToKebabCase(section.section_name), section.paths && section.paths.length ? (section.paths[0].methods[0].path || '') : '', section)
}
}, [section.section_name])
const [containerRef, isInView] = useInView({
root: null,
rootMargin: "0px 0px -80% 0px",
@@ -70,7 +77,7 @@ const Section = ({ data, api }) => {
useEffect(() => {
const handleInView = () => {
if (isInView) {
updateSection(convertToKebabCase(section.section_name))
updateSection({id: convertToKebabCase(section.section_name), section})
}
}
handleInView()
@@ -188,6 +195,7 @@ const Section = ({ data, api }) => {
key={i}
data={m}
section={convertToKebabCase(section.section_name)}
sectionData={section}
pathname={p.name}
/>
)

28
www/reference/src/components/layout.js
View File

@@ -1,10 +1,30 @@
import { Box, Flex } from "theme-ui"
import React from "react"
import { Flex, Box } from "theme-ui"
import Sidebar from "./side-bar"
import styled from "@emotion/styled"
const LayoutContainer = styled(Flex)`
--side-bar-width: 220px;
@media screen and (min-width: 1680px) {
--side-bar-width: 280px;
}
`
const ContentBox = styled(Box)`
@media screen and (min-width: 849px) {
width: calc(100% - var(--side-bar-width));
}
@media screen and (max-width: 848px) {
width: 100%;
}
`
const Layout = ({ data, api, children }) => {
return (
<Flex sx={{ p: "0", m: "0", overflow: "hidden" }}>
<LayoutContainer sx={{ p: "0", m: "0", overflow: "hidden" }}>
<Flex
sx={{
position: "absolute",
@@ -17,9 +37,9 @@ const Layout = ({ data, api, children }) => {
}}
>
<Sidebar data={data} api={api} />
<Box>{children}</Box>
<ContentBox>{children}</ContentBox>
</Flex>
</Flex>
</LayoutContainer>
)
}

11
www/reference/src/components/search/hit-component.js
View File

@@ -1,9 +1,10 @@
import React, { useContext } from "react"
import { convertToKebabCase } from "../../utils/convert-to-kebab-case"
import NavigationContext from "../../context/navigation-context"
import { convertToKebabCase } from "../../utils/convert-to-kebab-case"
import { navigate } from "gatsby"
const HitComponent = ({ hit, children }) => {
const HitComponent = ({ hit, children, data }) => {
const { goTo, api } = useContext(NavigationContext)
let { url, type, hierarchy } = hit
@@ -20,13 +21,17 @@ const HitComponent = ({ hit, children }) => {
*/
const goToHierarchy = e => {
e.preventDefault()
//find section
let section = data.sections.find((s) => s.section.section_name == hierarchy.lvl1);
section = section ? section.section : {}
if (hierarchy.lvl2) {
goTo({
section: convertToKebabCase(hierarchy.lvl1),
method: convertToKebabCase(hierarchy.lvl2),
sectionObj: section
})
} else {
goTo({ section: convertToKebabCase(hierarchy.lvl1) })
goTo({ section: convertToKebabCase(hierarchy.lvl1), sectionObj: section })
}
}

16
www/reference/src/components/search/index.js
View File

@@ -1,6 +1,8 @@
import React, { useContext } from "react"
import { DocSearch } from "@docsearch/react"
import "../../medusa-plugin-themes/docsearch/theme.css"
import React, { useContext } from "react"
import { DocSearch } from "@docsearch/react"
import HitComponent from "./hit-component"
import NavigationContext from "../../context/navigation-context"
import { convertToKebabCase } from "../../utils/convert-to-kebab-case"
@@ -8,7 +10,7 @@ import { navigate } from "gatsby-link"
const algoliaApiKey = process.env.ALGOLIA_API_KEY || "temp"
const Search = () => {
const Search = ({data}) => {
const { goTo, api } = useContext(NavigationContext)
const getOtherAPI = () => {
@@ -36,13 +38,17 @@ const Search = () => {
*/
const goToHierarchy = item => {
const { hierarchy } = item
//find section
let section = data.sections.find((s) => s.section.section_name == hierarchy.lvl1);
section = section ? section.section : {}
if (hierarchy.lvl2) {
goTo({
section: convertToKebabCase(hierarchy.lvl1),
method: convertToKebabCase(hierarchy.lvl2),
sectionObj: section
})
} else {
goTo({ section: convertToKebabCase(hierarchy.lvl1) })
goTo({ section: convertToKebabCase(hierarchy.lvl1), sectionObj: section })
}
}
@@ -67,7 +73,7 @@ const Search = () => {
<DocSearch
apiKey={algoliaApiKey}
indexName="medusa-commerce"
hitComponent={HitComponent}
hitComponent={({hit, children}) => <HitComponent data={data} hit={hit} children={children} />}
navigator={{
navigate({ item }) {
if (item.url.includes(`api/${api}`)) {

11
www/reference/src/components/side-bar/index.js
View File

@@ -1,19 +1,14 @@
import { Box, Flex, Image } from "theme-ui"
import React, { useEffect, useState } from "react"
import { Flex, Image, Box } from "theme-ui"
import styled from "@emotion/styled"
import Logo from "../../assets/logo.svg"
import LogoMuted from "../../assets/logo-muted.svg"
import SideBarItem from "./sidebar-item"
import SideBarSelector from "./sidebar-selector"
import { navigate } from "gatsby"
import styled from "@emotion/styled"
const SideBarContainer = styled(Flex)`
--side-bar-width: 220px;
@media screen and (min-width: 1680px) {
--side-bar-width: 280px;
}
@media screen and (max-width: 848px) {
display: none;
}

26
www/reference/src/components/side-bar/sidebar-item.js
View File

@@ -1,10 +1,11 @@
import React, { useContext } from "react"
import Collapsible from "react-collapsible"
import { Flex, Box, Text } from "theme-ui"
import styled from "@emotion/styled"
import { convertToKebabCase } from "../../utils/convert-to-kebab-case"
import { Box, Flex, Text } from "theme-ui"
import React, { useContext, useEffect, useState } from "react"
import ChevronDown from "../icons/chevron-down"
import Collapsible from "react-collapsible"
import NavigationContext from "../../context/navigation-context"
import { convertToKebabCase } from "../../utils/convert-to-kebab-case"
import styled from "@emotion/styled"
const StyledCollapsible = styled(Collapsible)`
margin-bottom: 10px;
@@ -26,6 +27,7 @@ const SideBarItem = ({ item }) => {
currentSection,
goTo,
} = useContext(NavigationContext)
const [isOpen, setIsOpen] = useState(false);
const { section } = item
const subItems = section.paths
.map(p => {
@@ -47,16 +49,21 @@ const SideBarItem = ({ item }) => {
if (element) {
element.scrollIntoView()
if (!openSections.includes(id)) {
openSection(id)
openSection({id, section})
}
}
}
const handleSubClick = path => {
const id = convertToKebabCase(section.section_name)
goTo({ section: id, method: path })
goTo({ section: id, method: path, sectionObj: section })
}
useEffect(() => {
setIsOpen(currentSection === convertToKebabCase(section.section_name) ||
openSections.includes(convertToKebabCase(section.section_name)));
}, [section.section_name, currentSection, openSections])
return (
<Container id={`nav-${convertToKebabCase(section.section_name)}`}>
<StyledCollapsible
@@ -86,10 +93,7 @@ const SideBarItem = ({ item }) => {
{section.section_name} <ChevronDown />
</Flex>
}
open={
currentSection === convertToKebabCase(section.section_name) ||
openSections.includes(convertToKebabCase(section.section_name))
}
open={isOpen}
onTriggerOpening={handleClick}
transitionTime={1}
>

15
www/reference/src/components/topbar.js
View File

@@ -1,12 +1,12 @@
import { Box, Flex, Link, Select } from "@theme-ui/components"
import { navigate } from "gatsby-link"
import React, { useContext } from "react"
import ChevronDown from "./icons/chevron-down"
import GitHub from "../components/icons/github"
import NavigationContext from "../context/navigation-context"
import { convertToKebabCase } from "../utils/convert-to-kebab-case"
import ChevronDown from "./icons/chevron-down"
import Search from "./search"
import { convertToKebabCase } from "../utils/convert-to-kebab-case"
import { navigate } from "gatsby-link"
const Topbar = ({ data, api }) => {
const { goTo, reset, currentSection } = useContext(NavigationContext)
@@ -15,7 +15,10 @@ const Topbar = ({ data, api }) => {
const parts = e.target.value.split(" ")
if (parts[0] === api) {
goTo({ section: parts[1] })
//find section
let sectionObj = data.sections.find((s) => convertToKebabCase(s.section.section_name) === parts[1]);
sectionObj = sectionObj ? sectionObj.section : {};
goTo({ section: parts[1], sectionObj })
} else {
reset()
navigate(`/api/${api === "admin" ? "store" : "admin"}`)
@@ -112,7 +115,7 @@ const Topbar = ({ data, api }) => {
>
<GitHub />
</Link>
<Search />
<Search data={data} />
</Flex>
</Flex>
)

67
www/reference/src/context/navigation-context.js
View File

@@ -1,4 +1,5 @@
import React, { useReducer } from "react"
import { checkDisplay } from "../utils/check-display"
import scrollParent from "../utils/scroll-parent"
import types from "./types"
@@ -7,6 +8,11 @@ export const defaultNavigationContext = {
api: "null",
setApi: () => {},
currentSection: null,
currentSectionObj: {
section_name: "",
paths: [],
schema: {}
},
updateSection: () => {},
currentHash: null,
updateHash: () => {},
@@ -21,6 +27,7 @@ const NavigationContext = React.createContext(defaultNavigationContext)
export default NavigationContext
const reducer = (state, action) => {
let obj = []
switch (action.type) {
case types.SET_API: {
return {
@@ -29,23 +36,30 @@ const reducer = (state, action) => {
}
}
case types.UPDATE_HASH:
return {
...state,
currentSection: action.payload.section,
currentHash: action.payload.method,
}
case types.UPDATE_SECTION:
return {
...state,
currentSection: action.payload,
currentHash: null,
}
case types.OPEN_SECTION:
const obj = state.openSections
obj.push(action.payload)
obj.push(action.payload.section)
return {
...state,
openSections: obj,
currentSection: action.payload.section,
currentHash: action.payload.method,
currentSectionObj: action.payload.sectionObj
}
case types.UPDATE_SECTION:
obj.push(action.payload.id)
return {
...state,
openSections: obj,
currentSection: action.payload.id,
currentHash: null,
currentSectionObj: action.payload.section
}
case types.OPEN_SECTION:
obj.push(action.payload.id)
return {
...state,
openSections: obj,
currentSection: action.payload.id,
currentSectionObj: action.payload.section
}
case types.RESET:
return {
@@ -53,6 +67,11 @@ const reducer = (state, action) => {
openSections: [],
currentSection: null,
currentHash: null,
currentSectionObj: {
section_name: "",
paths: [],
schema: {}
}
}
case types.UPDATE_METADATA:
return {
@@ -108,10 +127,10 @@ export const NavigationProvider = ({ children }) => {
dispatch({ type: types.UPDATE_METADATA, payload: metadata })
}
const updateHash = (section, method) => {
const updateHash = (section, method, sectionObj) => {
dispatch({
type: types.UPDATE_HASH,
payload: { method: method, section: section },
payload: { method: method, section: section, sectionObj },
})
window.history.replaceState(
null,
@@ -121,21 +140,21 @@ export const NavigationProvider = ({ children }) => {
scrollNav(method)
}
const updateSection = section => {
dispatch({ type: types.UPDATE_SECTION, payload: section })
window.history.replaceState(null, "", `/api/${state.api}/${section}`)
scrollNav(section)
const updateSection = ({id, section}) => {
dispatch({ type: types.UPDATE_SECTION, payload: {id, section} })
window.history.replaceState(null, "", `/api/${state.api}/${id}`)
scrollNav(id)
}
const openSection = sectionName => {
dispatch({ type: types.OPEN_SECTION, payload: sectionName })
const openSection = ({id, section}) => {
dispatch({ type: types.OPEN_SECTION, payload: {id, section} })
}
const goTo = to => {
const { section, method } = to
const { section, method, sectionObj } = to
if (!state.openSections.includes(section)) {
openSection(section)
openSection({id: section, section: sectionObj})
}
scrollToElement(method || section)
}

19
www/reference/src/templates/reference-page.js
View File

@@ -1,14 +1,15 @@
import React, { useContext, useEffect, useState } from "react"
import { Helmet } from "react-helmet"
import Layout from "../components/layout"
import Content from "../components/content"
import { Helmet } from "react-helmet"
import Layout from "../components/layout"
import NavigationContext from "../context/navigation-context"
import { convertToKebabCase } from "../utils/convert-to-kebab-case"
export default function ReferencePage({
pageContext: { data, api, title, description, to },
}) {
const { setApi, goTo, metadata } = useContext(NavigationContext)
const { setApi, goTo, metadata, currentSection, currentSectionObj } = useContext(NavigationContext)
const [siteData, setSiteData] = useState({
title: title,
description: description,
@@ -18,6 +19,14 @@ export default function ReferencePage({
setApi(api)
if (to) {
goTo(to)
} else if (data.sections && data.sections.length) {
//go to the first section
const firstSection = data.sections[0].section;
goTo({
section: convertToKebabCase(firstSection.section_name),
method: firstSection.paths && firstSection.paths.length ? firstSection.paths[0].methods[0].method : '',
sectionObj: firstSection
})
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [])
@@ -34,10 +43,10 @@ export default function ReferencePage({
return (
<Layout data={data} api={api}>
<Helmet>
<title>{`API | Medusa Commerce API Reference`}</title>
<title>{`API | Medusa API Reference`}</title>
<meta name="description" content={siteData.description} />
</Helmet>
<Content data={data} api={api} />
<Content data={data} currentSection={currentSectionObj} api={api} />
</Layout>
)
}