Initial commit

2026-03-07 11:07:45 -03:00
commit 9d523f8b6a
65 changed files with 17311 additions and 0 deletions
--- a/.agents/skills/building-with-medusa/reference/module-links.md
+++ b/.agents/skills/building-with-medusa/reference/module-links.md
@@ -0,0 +1,384 @@
+# Module Links
+
+## Contents
+- [When to Use Links](#when-to-use-links)
+- [Implementing Module Links - Workflow Checklist](#implementing-module-links---workflow-checklist)
+- [Step 1: Defining a Link](#step-1-defining-a-link)
+- [Step 2: Link Configuration Options](#step-2-link-configuration-options)
+  - [List Links (One-to-Many)](#list-links-one-to-many)
+  - [Delete Cascades](#delete-cascades)
+- [Step 3: Sync Links (Run Migrations)](#step-3-sync-links-run-migrations)
+- [Step 4: Managing Links](#step-4-managing-links)
+- [Step 5: Querying Linked Data](#step-5-querying-linked-data)
+- [Advanced: Link with Custom Columns](#advanced-link-with-custom-columns)
+
+Module links create associations between data models in different modules while maintaining module isolation. Use links to connect your custom models to Commerce Module models (products, customers, orders, etc.).
+
+## When to Use Links
+
+- **Extend commerce entities**: Add brands to products, wishlists to customers
+- **Cross-module associations**: Connect custom modules to each other
+- **Maintain isolation**: Keep modules independent and reusable
+
+## Implementing Module Links - Workflow Checklist
+
+**IMPORTANT FOR CLAUDE CODE**: When implementing module links, use the TodoWrite tool to track your progress through these steps. This ensures you don't miss any critical steps and provides visibility to the user.
+
+Create these tasks in your todo list:
+
+- Optional: Add linked ID in custom data model (if one-to-one or one-to-many)
+- Define the link in src/links/
+- Configure list or delete cascade options if needed
+- **CRITICAL: Run migrations: npx medusa db:migrate** (Never skip this step!)
+- Create links in code using link.create() or createRemoteLinkStep
+- Query linked data using query.graph()
+- **CRITICAL: Run build to validate implementation** (catches type errors and issues)
+
+## Optional: Add Linked ID in Custom Data Model
+
+Add the ID of a linked data model in the custom data model if the custom data model belongs to it or extends it. Otherwise, skip this step.
+
+For example, add ID of customer and product to custom product review model:
+
+```typescript
+import { model } from "@medusajs/framework/utils"
+
+const Review = model.define("review", {
+  // other properties...
+  // ID of linked customer
+  customer_id: model.text(),
+  // ID of linked product
+  product_id: model.text()
+})
+
+export default Review
+```
+
+## Step 1: Defining a Link
+
+**⚠️ CRITICAL RULE: Create ONE link definition per file.** Do NOT export an array of links from a single file.
+
+Create link files in `src/links/`:
+
+```typescript
+// ✅ CORRECT - src/links/product-brand.ts (one link per file)
+import { defineLink } from "@medusajs/framework/utils"
+import ProductModule from "@medusajs/medusa/product"
+import BrandModule from "../modules/brand"
+
+export default defineLink(
+  ProductModule.linkable.product,
+  BrandModule.linkable.brand
+)
+```
+
+**If one model links to multiple others, create multiple files:**
+
+```typescript
+// ✅ CORRECT - src/links/review-product.ts
+export default defineLink(
+  ReviewModule.linkable.review,
+  ProductModule.linkable.product
+)
+
+// ✅ CORRECT - src/links/review-customer.ts
+export default defineLink(
+  ReviewModule.linkable.review,
+  CustomerModule.linkable.customer
+)
+
+// ❌ WRONG - Don't export array of links from one file
+export default [
+  defineLink(ReviewModule.linkable.review, ProductModule.linkable.product),
+  defineLink(ReviewModule.linkable.review, CustomerModule.linkable.customer),
+] // This doesn't work!
+```
+
+**IMPORTANT:** The `.linkable` property is **automatically added** to all modules by Medusa. You do NOT need to add `.linkable()` or any linkable definition to your data models. Simply use `ModuleName.linkable.modelName` when defining links.
+
+For example, if you have a `Review` data model in a `ReviewModule`:
+- ✅ CORRECT: `ReviewModule.linkable.review` (works automatically)
+- ❌ WRONG: Adding `.linkable()` method to the Review model definition (not needed, causes errors)
+
+**⚠️ NEXT STEP**: After defining a link, you MUST immediately proceed to Step 3 to run migrations (`npx medusa db:migrate`). Do not skip this step!
+
+## Step 2: Link Configuration Options
+
+### List Links (One-to-Many)
+
+Allow multiple records to link to one record:
+
+```typescript
+// A brand can have many products
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    isList: true,
+  },
+  BrandModule.linkable.brand
+)
+```
+
+### Delete Cascades
+
+Automatically delete links when a record is deleted:
+
+```typescript
+export default defineLink(ProductModule.linkable.product, {
+  linkable: BrandModule.linkable.brand,
+  deleteCascade: true,
+})
+```
+
+## Step 3: Sync Links (Run Migrations)
+
+**⚠️ CRITICAL - DO NOT SKIP**: After defining links, you MUST run migrations to sync the link to the database. Without this step, the link will not work and you will get runtime errors.
+
+```bash
+npx medusa db:migrate
+```
+
+**Why this matters:**
+- Links create database tables that store the relationships between modules
+- Without migrations, these tables don't exist and link operations will fail
+- This step is REQUIRED before creating any links in code or querying linked data
+
+**Common mistake:** Defining a link in `src/links/` and immediately trying to use it in a workflow or query without running migrations first. Always run migrations immediately after defining a link.
+
+## Step 4: Managing Links
+
+**⚠️ CRITICAL - Link Order (Direction):** When creating or dismissing links, the order of modules MUST match the order in `defineLink()`. Mismatched order causes runtime errors.
+
+```typescript
+// Example link definition: product FIRST, then brand
+export default defineLink(
+  ProductModule.linkable.product,
+  BrandModule.linkable.brand
+)
+```
+
+### In Workflow Composition Functions
+
+To create a link between records in workflow composition functions, use the `createRemoteLinkStep`:
+
+```typescript
+import { Modules } from "@medusajs/framework/utils"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+import {
+  createWorkflow,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+
+const BRAND_MODULE = "brand"
+
+export const myWorkflow = createWorkflow(
+  "my-workflow",
+  function (input) {
+    // ...
+    // ✅ CORRECT - Order matches defineLink (product first, then brand)
+    const linkData = transform({ input }, ({ input }) => {
+      return [
+        {
+          [Modules.PRODUCT]: {
+            product_id: input.product_id,
+          },
+          [BRAND_MODULE]: {
+            brand_id: input.brand_id,
+          },
+        },
+      ]
+    })
+
+    createRemoteLinkStep(linkData)
+    // ...
+  }
+)
+
+// ❌ WRONG - Order doesn't match defineLink
+const linkData = transform({ input }, ({ input }) => {
+  return [
+    {
+      [BRAND_MODULE]: {
+        brand_id: input.brand_id,
+      },
+      [Modules.PRODUCT]: {
+        product_id: input.product_id,
+      },
+    },
+  ]
+}) // Runtime error: link direction mismatch!
+```
+
+To dismiss (remove) a link between records in workflow composition functions, use the `dismissRemoteLinkStep`:
+
+```typescript
+import { Modules } from "@medusajs/framework/utils"
+import { dismissRemoteLinkStep } from "@medusajs/medusa/core-flows"
+import {
+  createWorkflow,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+
+const BRAND_MODULE = "brand"
+
+export const myWorkflow = createWorkflow(
+  "my-workflow",
+  function (input) {
+    // ...
+    // Order MUST match defineLink (product first, then brand)
+    const linkData = transform({ input }, ({ input }) => {
+      return [
+        {
+          [Modules.PRODUCT]: {
+            product_id: input.product_id,
+          },
+          [BRAND_MODULE]: {
+            brand_id: input.brand_id,
+          },
+        },
+      ]
+    })
+
+    dismissRemoteLinkStep(linkData)
+    // ...
+  }
+)
+```
+
+### Outside Workflows
+
+Outside workflows or in workflow steps, use the `link` utility to create and manage links between records. **Order MUST match `defineLink()` here too:**
+
+```typescript
+import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
+
+// In an API route or workflow step
+const link = container.resolve(ContainerRegistrationKeys.LINK)
+
+const BRAND_MODULE = "brand"
+
+// ✅ CORRECT - Create a link (order matches defineLink: product first, then brand)
+await link.create({
+  [Modules.PRODUCT]: { product_id: "prod_123" },
+  [BRAND_MODULE]: { brand_id: "brand_456" },
+})
+
+// ✅ CORRECT - Dismiss (remove) a link (same order: product first, then brand)
+await link.dismiss({
+  [Modules.PRODUCT]: { product_id: "prod_123" },
+  [BRAND_MODULE]: { brand_id: "brand_456" },
+})
+
+// ❌ WRONG - Order doesn't match defineLink
+await link.create({
+  [BRAND_MODULE]: { brand_id: "brand_456" },
+  [Modules.PRODUCT]: { product_id: "prod_123" },
+}) // Runtime error: link direction mismatch!
+```
+
+## Step 5: Querying Linked Data
+
+### Using query.graph() - Retrieve Linked Data
+
+Use `query.graph()` to fetch data across linked modules. **Note**: `query.graph()` can retrieve linked data but **cannot filter by properties of linked modules** (data models in separate modules).
+
+```typescript
+const query = container.resolve("query")
+
+// ✅ Get products with their linked brands (no cross-module filtering)
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "brand.*"], // brand.* fetches linked brand data
+  filters: {
+    id: "prod_123", // ✅ Filter by product properties only
+  },
+})
+
+// ✅ Get brands with their linked products
+const { data: brands } = await query.graph({
+  entity: "brand",
+  fields: ["id", "name", "products.*"],
+})
+
+// ❌ DOES NOT WORK: Cannot filter products by linked brand properties
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "brand.*"],
+  filters: {
+    brand: {
+      name: "Nike" // ❌ Fails: brand is in a different module
+    }
+  }
+})
+```
+
+### Using query.index() - Filter Across Linked Modules
+
+To filter by properties of linked modules (separate modules with module links), use `query.index()` from the Index Module:
+
+```typescript
+const query = container.resolve("query")
+
+// ✅ Filter products by linked brand name using Index Module
+const { data: products } = await query.index({
+  entity: "product",
+  fields: ["*", "brand.*"],
+  filters: {
+    brand: {
+      name: "Nike" // ✅ Works with Index Module!
+    }
+  }
+})
+```
+
+**Key Distinction:**
+- **Same module relations** (e.g., Product → ProductVariant): Use `query.graph()` - filtering works ✅
+- **Different module links** (e.g., Product → Brand): Use `query.index()` for filtering ✅
+
+**Index Module Requirements:**
+1. Install `@medusajs/index` package
+2. Add to `medusa-config.ts`
+3. Enable `MEDUSA_FF_INDEX_ENGINE=true` in `.env`
+4. Run `npx medusa db:migrate`
+5. Mark properties as `filterable` in link definition:
+
+```typescript
+// src/links/product-brand.ts
+defineLink(
+  { linkable: ProductModule.linkable.product, isList: true },
+  { linkable: BrandModule.linkable.brand, filterable: ["id", "name"] }
+)
+```
+
+See the [Querying Data reference](querying-data.md#querying-linked-data) for complete details on both methods.
+
+## Advanced: Link with Custom Columns
+
+Add extra data to the link table:
+
+```typescript
+export default defineLink(
+  ProductModule.linkable.product,
+  BrandModule.linkable.brand,
+  {
+    database: {
+      extraColumns: {
+        featured: {
+          type: "boolean",
+          defaultValue: "false",
+        },
+      },
+    },
+  }
+)
+```
+
+Set custom column values when creating links:
+
+```typescript
+await link.create({
+  product: { product_id: "prod_123" },
+  brand: { brand_id: "brand_456" },
+  data: { featured: true },
+})
+```