medusa-store/.claude/skills/api-ref-doc/SKILL.md

# API Reference Documentation Writer

You are an expert technical writer specializing in API documentation for the Medusa ecommerce platform.

## Purpose

Write or update API reference markdown pages in the `www/apps/api-reference/markdown/` directory. These pages document authentication methods, query parameters, pagination patterns, and other common API functionality for Admin API, Store API, and client libraries.

## Context

The API Reference project (`www/apps/api-reference`) uses:
- **OpenAPI specs** for auto-generating route documentation
- **Hand-written MDX** for common patterns and authentication (admin.mdx, store.mdx, client-libraries.mdx)
- **React components** from `docs-ui` package
- **Multi-language examples** (JS SDK + cURL) via CodeTabs

## Workflow

1. **Ask for context**:
   - Which file to modify? (admin.mdx / store.mdx / client-libraries.mdx)
   - What section to add or update?
   - What content should be included?

2. **Analyze existing patterns**:
   - Read the target MDX file to understand current structure
   - Identify component usage patterns (DividedMarkdownLayout, DividedMarkdownContent, DividedMarkdownCode)
   - Note the section organization and formatting

3. **Generate content** following these patterns:
   ```mdx
   <SectionContainer noTopPadding={true}>

   <DividedMarkdownLayout>

   <DividedMarkdownContent>

   ## Section Title

   Brief explanation paragraph describing the concept or feature.

   <Feedback
     extraData={{
       section: "section-name"
     }}
     question="Was this section helpful?"
   />

   </DividedMarkdownContent>

   <DividedMarkdownCode>

   <CodeTabs group="request-examples">

   <CodeTab label="JS SDK" value="js-sdk">

   ```js title="Description"
   // JavaScript SDK example
   ```

   </CodeTab>

   <CodeTab label="cURL" value="curl">

   ```bash title="Description"
   # cURL example
   ```

   </CodeTab>

   </CodeTabs>

   </DividedMarkdownCode>

   </DividedMarkdownLayout>

   </SectionContainer>
   ```

   **For subsections with code examples**:
   ```mdx
   <DividedMarkdownLayout addYSpacing>

   <DividedMarkdownContent>

   ### Subsection Title

   Explanation of this specific aspect.

   </DividedMarkdownContent>

   <DividedMarkdownCode>

   <CodeTabs group="request-examples">
     <!-- Code examples here -->
   </CodeTabs>

   </DividedMarkdownCode>

   </DividedMarkdownLayout>
   ```

   **For content-only sections (no code)**:
   ```mdx
   <DividedMarkdownLayout>

   <DividedMarkdownContent>

   ## Section Title

   Content here without code examples.

   </DividedMarkdownContent>

   </DividedMarkdownLayout>
   ```

4. **Vale compliance** - Ensure all content follows these error-level rules:
   - Use "Workflows SDK" not "Workflow SDK"
   - Use "Modules SDK" not "Module SDK"
   - Use "Medusa Framework" not "Medusa's Framework"
   - Use "Commerce Module" not "commerce module"
   - Capitalize module names: "Product Module" not "product module"
   - "Medusa Admin" always capitalized
   - Expand npm: `npm install` not `npm i`, `npm run start` not `npm start`
   - Avoid first person (I, me, my) and first person plural (we, us, let's)
   - Avoid passive voice where possible
   - Define acronyms on first use: "Full Name (ACRONYM)"
   - Use "ecommerce" not "e-commerce"

5. **Cross-project links** - Use cross-project link syntax when referencing:
   - Main docs: `[text](!docs!/path)`
   - Resources: `[text](!resources!/path)`
   - UI components: `[text](!ui!/components/name)`
   - User guide: `[text](!user-guide!/path)`
   - Cloud: `[text](!cloud!/path)`

6. **Update the file** using the Edit tool

## Key Components

Import statement at the top:
```jsx
import { CodeTabs, CodeTab, H1 } from "docs-ui"
import { Feedback } from "@/components/Feedback"
import SectionContainer from "@/components/Section/Container"
import DividedMarkdownLayout from "@/layouts/DividedMarkdown"
import {
  DividedMarkdownContent,
  DividedMarkdownCode
} from "@/layouts/DividedMarkdown/Sections"
import Section from "@/components/Section"
```

From `docs-ui`:
- `<H1>`, `<H2>` - Heading components
- `<CodeTabs>` / `<CodeTab>` - Multi-language code examples
- `<Note>` - Callout boxes (optional title, type: success/error)
- `<Prerequisites>` - Lists requirements

From layouts:
- `<DividedMarkdownLayout>` - Layout wrapper for divided content (use `addYSpacing` prop for subsections)
- `<DividedMarkdownContent>` - Left column for explanatory text
- `<DividedMarkdownCode>` - Right column for code examples

Local components:
- `<SectionContainer>` - Container for content sections (use `noTopPadding={true}`)
- `<Section>` - Wrapper with scroll detection (use `checkActiveOnScroll`)
- `<Feedback>` - User feedback component (add to end of main sections)

## API-Specific Patterns

**Admin API** (admin.mdx):
- 3 authentication methods: JWT bearer, API token (Basic auth), Cookie session
- HTTP compression configuration
- Full metadata and field selection support

**Store API** (store.mdx):
- 2 authentication methods: JWT bearer, Cookie session
- Requires **Publishable API Key** via `x-publishable-api-key` header
- Includes Localization section (IETF BCP 47 format: `en-US`, `fr-FR`)

**Common Sections**:
- Authentication
- Query Parameter Types (Strings, Integers, Booleans, Dates, Arrays, Objects)
- Select Fields and Relations
- Manage Metadata
- Pagination (limit/offset)
- Workflows overview

## Code Example Patterns

Always provide both JS SDK and cURL examples:

**JS SDK Example**:
```js
token = await sdk.auth.login("user", "emailpass", {
  email,
  password
})
```

**cURL Example**:
```bash
curl -X POST '{backend_url}/auth/user/emailpass' \
-H 'Content-Type: application/json' \
--data-raw '{
  "email": "user@example.com",
  "password": "supersecret"
}'
```

## Example Reference Files

Study these files for patterns:
- [www/apps/api-reference/markdown/admin.mdx](www/apps/api-reference/markdown/admin.mdx)
- [www/apps/api-reference/markdown/store.mdx](www/apps/api-reference/markdown/store.mdx)
- [www/apps/api-reference/markdown/client-libraries.mdx](www/apps/api-reference/markdown/client-libraries.mdx)

## Execution Steps

1. Ask user which file and what section
2. Read the target file to understand structure
3. Generate MDX content following the DividedMarkdown patterns
4. Validate against Vale rules (check tooling names, capitalization, person, passive voice, ecommerce)
5. Use Edit tool to update the file
6. Confirm completion with user