docs: improve link docs for commerce modules (#10726)

2024-12-24 17:19:39 +02:00
parent 83925f5c7a
commit 8441d2ab9d
21 changed files with 3693 additions and 37 deletions
@@ -1,3 +1,5 @@
+import { CodeTabs, CodeTab } from "docs-ui"
+
 export const metadata = {
  title: `Links between API Key Module and Other Modules`,
 }
@@ -6,6 +8,14 @@ export const metadata = {

 This document showcases the module links defined between the API Key Module and other commerce modules.

+## Summary
+
+The API Key Module has the following links to other modules:
+
+- [`ApiKey` data model \<\> `SalesChannel` data model of Sales Channel Module](#sales-channel-module).
+
+---
+
 ## Sales Channel Module

 You can create a publishable API key and associate it with a sales channel. Medusa defines a link between the `ApiKey` and the `SalesChannel` data models.
@@ -15,3 +25,86 @@ You can create a publishable API key and associate it with a sales channel. Medu
 This is useful to avoid passing the sales channel's ID as a parameter of every request, and instead pass the publishable API key in the header of any request to the Store API route.

 Learn more about this in the [Sales Channel Module's documentation](../../sales-channel/publishable-api-keys/page.mdx).
+
+### Retrieve with Query
+
+To retrieve the sales channels of an API key with [Query](!docs!/learn/fundamentals/module-links/query), pass `sales_channels.*` in `fields`:
+
+<CodeTabs group="relation-query">
+  <CodeTab label="query.graph" value="method">
+
+```ts
+const { data: apiKeys } = await query.graph({
+  entity: "api_key",
+  fields: [
+    "sales_channels.*"
+  ]
+})
+
+// apiKeys.sales_channels
+```
+
+  </CodeTab>
+  <CodeTab label="useQueryGraphStep" value="step">
+
+```ts
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+const { data: apiKeys } = useQueryGraphStep({
+  entity: "api_key",
+  fields: [
+    "sales_channels.*"
+  ]
+})
+
+// apiKeys.sales_channels
+```
+
+  </CodeTab>
+</CodeTabs>
+
+### Manage with Remote Link
+
+To manage the sales channels of an API key, use [Remote Link](!docs!/learn/fundamentals/module-links/remote-link):
+
+<CodeTabs group="relation-link">
+  <CodeTab label="remoteLink.create" value="method">
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+// ...
+
+await remoteLink.create({
+  [Modules.API_KEY]: {
+    api_key_id: "apk_123",
+  },
+  [Modules.SALES_CHANNEL]: {
+    sales_channel_id: "sc_123",
+  },
+})
+```
+
+  </CodeTab>
+  <CodeTab label="createRemoteLinkStep" value="step">
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+
+// ...
+
+createRemoteLinkStep({
+  [Modules.API_KEY]: {
+    api_key_id: "apk_123",
+  },
+  [Modules.SALES_CHANNEL]: {
+    sales_channel_id: "sc_123",
+  },
+})
+```
+
+  </CodeTab>
+</CodeTabs>