Merge branch 'master' into develop

2023-01-11 16:46:32 +01:00
parent a8bde8ba74 3b632c5130
commit 6dafb51547
44 changed files with 1103 additions and 224 deletions
@@ -60,27 +60,7 @@ A basic Medusa server installed with the `medusa new` command has dependencies s
 }
 ```

-For a plugin, a lot of these dependencies are not necessary or should be labeled as [peer dependencies](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependencies). Therefore, it’s important to make changes to the dependencies of your plugin.
-
-The recommended change is the following:
-
-```json title=package.json
-"peerDependencies": {
-  "@medusajs/medusa": "^1.3.1",
-  "medusa-interfaces": "^1.3.0",
-  "typeorm": "^0.2.36"
-},
-"devDependencies": {
-  "@babel/cli": "^7.14.3",
-  "@babel/core": "^7.14.3",
-  "@babel/preset-typescript": "^7.14.5",
-  "babel-preset-medusa-package": "^1.1.19",
-}
-```
-
-The packages `@medusajs/medusa` and `medusa-interfaces` act as peer dependencies. They’ll be installed while you develop your package, and they are required when your plugin is installed in another NPM project.
-
-You remove the packages `medusa-fulfillment-manual`, `medusa-payment-manual`, and `medusa-payment-stripe` as they are fulfillment and payment plugins necessary for a Medusa server, but not for a plugin.
+For a plugin, some dependencies are not necessary. You can remove the packages `medusa-fulfillment-manual`, `medusa-payment-manual`, and `medusa-payment-stripe` as they are fulfillment and payment plugins necessary for a Medusa server, but not for a plugin.

 Additionally, you remove `@medusajs/medusa-cli` as you don’t need to use the Medusa CLI while developing a plugin.

@@ -0,0 +1,111 @@
+# Publishable API Keys Overview
+
+In this document, you’ll learn about Publishable API Keys and their usage.
+
+## Introduction
+
+While using Medusa’s APIs, you might have to pass some query parameters for certain resources with every or most requests.
+
+Taking Sales Channels as an example, you have to pass the Sales Channel’s ID as a query parameter to all the necessary endpoints, such as the List Products endpoint.
+
+This is a tedious and error-prone process. This is where Publishable API Keys are useful.
+
+Publishable API Keys can be used to scope API calls with an API key, determining what resources are retrieved when querying the API. Currently, they can be associated only with Sales Channels.
+
+For example, you can associate an API key with a B2B channel, then, on the storefront, retrieve only products available in that channel using the API key.
+
+---
+
+## PublishableApiKey Entity Overview
+
+The `PublishableApiKey` entity represents a publishable API key that is stored in the database. Some of its important attributes include:
+
+- `id`: The ID of the publishable API key. This is the API key you’ll use in your API requests.
+- `created_by`: The ID of the user that created this API key.
+- `revoked_by`: The ID of the user that revoked this API key. A revoked publishable API key cannot be used in requests.
+
+---
+
+## Relation to Other Entities
+
+### Sales Channels
+
+A publishable API key can be associated with more than one sales channel, and a sales channel can be associated with more than one publishable API key.
+
+The relation is represented by the entity `PublishableApiKeySalesChannel`.
+
+---
+
+## Using Publishable API Keys in Requests
+
+:::note
+
+Publishable API keys are only for client-side use. They can be publicly accessible in your code, as they are not authorized for the Admin API.
+
+:::
+
+### Using Medusa JS Client
+
+When using [Medusa’s JS Client](../../../js-client/overview.md), you can pass it to the client only once when you create the instance of the client:
+
+```ts
+const medusa = new Medusa({
+  maxRetries: 3,
+  baseUrl: "https://api.example.com",
+  publishableApiKey,
+})
+```
+
+This will add the API key as in the header parameter `x-publishable-api-key` on all requests.
+
+You can also use the `setPublishableKey` method to set it at a later point:
+
+```ts
+const medusa = new Medusa({
+  // ...
+})
+
+// at a later point
+medusa.setPublishableKey(publishableApiKey)
+```
+
+### Using Medusa React
+
+You can pass the publishable API key to the `MedusaProvider` component:
+
+```tsx
+const App = () => {
+  return (
+    <MedusaProvider
+      queryClientProviderProps={{ client: queryClient }}
+      baseUrl="http://localhost:9000"
+      // ...
+      publishableApiKey={publishableApiKey}
+    >
+      <MyStorefront />
+    </MedusaProvider>
+  )
+}
+```
+
+Then, the API key will be passed in the header parameter `x-publishable-api-key` of every request.
+
+### Using Other Methods
+
+For other ways of sending requests to your Medusa server, such as using the Fetch API, you must pass `x-publishable-api-key` in the header of every request. Its value is the publishable API key’s `id`.
+
+```ts
+fetch(`<SERVER_URL>/store/products`, {
+  credentials: "include",
+  headers: {
+    "x-publishable-api-key": publishableApiKey,
+  },
+})
+```
+
+---
+
+## See Also
+
+- [How to manage publishable keys as an admin](../../admin/manage-publishable-api-keys.mdx)
+- [Publishable API keys admin API reference](/api/admin/#tag/PublishableApiKey)
@@ -2,17 +2,6 @@

 In this document, you’ll learn about Sales Channels and how they can be used in Medusa.

-:::note
-
-The Sales Channels feature is currently in beta mode and guarded by a feature flag. To use Sales Channels either:
-
-1. Enable the `MEDUSA_FF_SALES_CHANNELS` environment variable;
-2. Or enable the `sales_channels` key in the Medusa server's settings.
-
-You can learn more about enabling it in the [feature flags](../feature-flags/toggle.md) documentation.
-
-:::
-
 ## Introduction

 Sales Channels allow you to separate between the different channels you sell products in. For example, you can have a sales channel for your website and another for your mobile apps.
@@ -0,0 +1,53 @@
+---
+description: 'Actions Required for v.1.7.3'
+---
+
+# v1.7.3
+
+Version 1.7.3 of Medusa changes the feature flag value for Sales Channels and Publishable API Keys.
+
+## Overview
+
+Sales Channels and Publishable API Keys were introduced in previous versions of Medusa, but guarded by [feature flags](../feature-flags/toggle.md) This meant that developers had to manually enable them to use them.
+
+Version 1.7.3 of Medusa keeps the feature flags for these two features, but they’re now enabled by default. This requires running the necessary migrations to ensure your server works as expected.
+
+---
+
+## Actions Required
+
+### Run Migrations
+
+After updating your Medusa server and before running it, run the following command to run the latest migration:
+
+```bash
+medusa migrations run
+```
+
+### Run Migration Script for Sales Channels
+
+With the introduction of Sales Channels, products are now associated with them. To avoid inconsistencies with how products are linked to Sales Channels, it’s strongly recommended to run a migration script before running the Medusa server.
+
+Start by adding the following environment variables:
+
+```bash
+TYPEORM_CONNECTION=postgres
+TYPEORM_URL=<DATABASE_URL>
+TYPEORM_LOGGING=true
+TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
+TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
+```
+
+Make sure to replace `<DATABASE_URL>` with the connection URL of your database.
+
+Then, run the following command in the root of your Medusa server:
+
+```bash
+node ./node_modules/@medusajs/medusa/dist/scripts/sales-channels-migration.js
+```
+
+---
+
+## Disabling Feature Flags
+
+Although this version enables Sales Channels and Publishable API Keys by default, you can still turn them off using feature flags. Learn more in [this documentation](../feature-flags/toggle.md#disable-feature-flags)