@mercurjs/docs 2.2.0-canary.40

package/content/tools/api-client.mdx

@@ -0,0 +1,155 @@
+---
+title: "API Client"
+description: "Type-safe client for consuming Mercur APIs."
+---
+
+`@mercurjs/client` provides a type-safe way to interact with your Mercur backend. Every endpoint, request input, and response is fully typed — inferred directly from your backend routes.
+
+## Installation
+
+```bash
+bun add @mercurjs/client
+```
+
+## Create a client
+
+```typescript
+import { createClient } from "@mercurjs/client";
+import type { Routes } from "./.mercur/_generated";
+
+export const client = createClient<Routes>({
+  baseUrl: "http://localhost:9000",
+});
+```
+
+<Info>
+  The `Routes` type is generated from your backend using `@mercurjs/cli@rc
+  codegen`. This gives the client full type safety with zero manual type
+  definitions.
+</Info>
+
+You can pass default fetch options for authentication or other headers:
+
+```typescript
+export const client = createClient<Routes>({
+  baseUrl: "http://localhost:9000",
+  fetchOptions: {
+    credentials: "include",
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  },
+});
+```
+
+## Calling APIs
+
+The client exposes three methods:
+
+```typescript
+// GET — fetch data
+const { reviews } = await client.vendor.reviews.query({ limit: 10 });
+
+// POST — create or update
+const { product } = await client.vendor.products.mutate({
+  title: "New Product",
+  status: "draft",
+});
+
+// DELETE — remove a resource
+await client.vendor.reviews.$id.delete({ $id: "rev_123" });
+```
+
+Use `$`-prefixed keys for path parameters:
+
+```typescript
+const { review } = await client.vendor.reviews.$id.query({
+  $id: "rev_123",
+});
+```
+
+Override fetch options per request when needed:
+
+```typescript
+const { reviews } = await client.vendor.reviews.query({
+  fetchOptions: {
+    signal: abortController.signal,
+  },
+});
+```
+
+## Inferring types
+
+Extract input and output types from any client method using `InferClientInput` and `InferClientOutput`:
+
+```typescript
+import type { InferClientInput, InferClientOutput } from "@mercurjs/client";
+
+type ListInput = InferClientInput<typeof client.vendor.reviews.query>;
+type ReviewDTO = InferClientOutput<
+  typeof client.vendor.reviews.$id.query
+>["review"];
+```
+
+## React Query
+
+The client returns plain Promises, so it works with any data-fetching library. Here's a typical pattern with TanStack React Query:
+
+```typescript
+import { useQuery } from "@tanstack/react-query";
+import { client } from "../lib/client";
+
+export function useReviews(
+  query?: InferClientInput<typeof client.vendor.reviews.query>,
+) {
+  const { data, ...rest } = useQuery({
+    queryKey: ["reviews", query],
+    queryFn: () => client.vendor.reviews.query(query),
+  });
+
+  return { ...data, ...rest };
+}
+```
+
+## Error handling
+
+Failed requests throw a `ClientError`:
+
+```typescript
+import { ClientError } from "@mercurjs/client";
+
+try {
+  await client.vendor.reviews.$id.query({ $id: "invalid" });
+} catch (error) {
+  if (error instanceof ClientError) {
+    error.message; // "Review not found"
+    error.status; // 404
+    error.statusText; // "Not Found"
+  }
+}
+```
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Why is a route missing from the client after I added it?">
+    The client's types come from the generated route map — run `bunx @mercurjs/cli@rc codegen` after adding or changing route files. During development, `codegen --watch` keeps the map current automatically.
+  </Accordion>
+  <Accordion title="How are URLs derived from property access?">
+    Each property becomes a kebab-cased path segment (`client.vendor.salesSummary` → `/vendor/sales-summary`), `$`-prefixed keys fill path parameters, and the terminal method picks the HTTP verb: `query` → GET, `mutate` → POST, `delete` → DELETE.
+  </Accordion>
+  <Accordion title="Can I upload files through the client?">
+    Yes — pass `Blob`/`File` values in the payload and the client switches to multipart form data automatically.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a custom API route" href="/rc/resources/tutorials/custom-api-route">
+    Build a route and call it through the client, end to end.
+  </Card>
+  <Card title="CLI" href="/rc/tools/cli">
+    The codegen command that generates the client's route map.
+  </Card>
+</CardGroup>

package/content/tools/cli.mdx

@@ -0,0 +1,196 @@
+---
+title: "CLI"
+description: "Install blocks, scaffold projects, and generate types from the command line."
+---
+
+The Mercur CLI (`@mercurjs/cli@rc`) manages your marketplace project — installing blocks, generating types, and checking for updates. To create a new project, use [`create-mercur-app`](https://www.npmjs.com/package/create-mercur-app).
+
+## Installation
+
+```bash
+bun add -g @mercurjs/cli@rc
+```
+
+## Commands
+
+### create
+
+Scaffolding new projects lives in the standalone [`create-mercur-app`](https://www.npmjs.com/package/create-mercur-app) package, so it downloads fast and works with every package manager's `create` command.
+
+```bash
+bun create mercur-app@rc my-marketplace
+# or
+npm create mercur-app@rc my-marketplace
+```
+
+It will prompt you for database credentials and install dependencies automatically.
+
+| Option | Description |
+|--------|-------------|
+| `-t, --template <template>` | Template to use (default: `basic`) |
+| `--no-deps` | Skip dependency installation |
+| `--skip-db` | Skip database configuration |
+| `--db-connection-string <string>` | PostgreSQL connection string |
+
+### init
+
+Initialize an existing project by creating a `blocks.json` configuration file.
+
+```bash
+bunx @mercurjs/cli@rc init
+```
+
+This sets up path aliases so the CLI knows where to place blocks in your project:
+
+```json
+{
+  "aliases": {
+    "api": "packages/api/src",
+    "vendor": "apps/vendor/src",
+    "admin": "apps/admin/src"
+  }
+}
+```
+
+| Option | Description |
+|--------|-------------|
+| `-d, --defaults` | Use default paths without prompting |
+| `-s, --silent` | Suppress output |
+
+### add
+
+Install blocks from the registry into your project.
+
+```bash
+bunx @mercurjs/cli@rc add wishlist
+bunx @mercurjs/cli@rc add product-review order-tracking
+```
+
+Blocks are copied directly into your project as source code. The CLI resolves dependencies, transforms imports to match your path aliases, and installs required packages.
+
+| Option | Description |
+|--------|-------------|
+| `-o, --overwrite` | Overwrite existing files |
+| `-y, --yes` | Skip confirmation |
+| `-s, --silent` | Suppress output |
+
+### search
+
+Find available blocks in the registry.
+
+```bash
+bunx @mercurjs/cli@rc search --query wishlist
+```
+
+| Option | Description |
+|--------|-------------|
+| `-q, --query <query>` | Search by name or description |
+| `-r, --registry <registry>` | Registry to search (default: `@mercurjs`) |
+
+### view
+
+Display detailed information about a block.
+
+```bash
+bunx @mercurjs/cli@rc view wishlist
+```
+
+### diff
+
+Compare local blocks against registry versions to check for updates.
+
+```bash
+bunx @mercurjs/cli@rc diff wishlist
+```
+
+If there are changes you want, update with:
+
+```bash
+bunx @mercurjs/cli@rc add wishlist --overwrite
+```
+
+### codegen
+
+Generate TypeScript types from your API routes. Used by the [API Client](/rc/tools/api-client) for type-safe requests.
+
+```bash
+bunx @mercurjs/cli@rc codegen
+```
+
+| Option | Description |
+|--------|-------------|
+| `-w, --watch` | Watch for changes and regenerate automatically |
+
+### registry:build
+
+Build a custom registry from a `registry.json` file.
+
+```bash
+bunx @mercurjs/cli@rc build
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <path>` | Output directory (default: `./r`) |
+| `-v, --verbose` | Show detailed output |
+
+### info
+
+Display project configuration and diagnostics.
+
+```bash
+bunx @mercurjs/cli@rc info
+```
+
+### telemetry
+
+Control anonymous usage data collection.
+
+```bash
+bunx @mercurjs/cli@rc telemetry --disable
+bunx @mercurjs/cli@rc telemetry --enable
+```
+
+## Custom registries
+
+Add custom block registries to your `blocks.json`:
+
+```json
+{
+  "registries": {
+    "@mercurjs": "https://registry.mercurjs.com/{name}",
+    "@my-registry": "https://my-registry.com/blocks/{name}.json"
+  }
+}
+```
+
+Use `{name}` as a placeholder for block names. Reference custom registries with the `-r` flag:
+
+```bash
+bunx @mercurjs/cli@rc search --query review --registry @my-registry
+```
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="When do I use create vs init?">
+    `create` scaffolds a brand-new project from a template. `init` only writes a `blocks.json` into an **existing** project so the CLI knows where to place blocks — use it when adopting blocks in a repo that wasn't created by the CLI.
+  </Accordion>
+  <Accordion title="When do I need to run codegen?">
+    After any change to API route files — added routes, changed validators, renamed paths. The [typed client](/rc/tools/api-client) reads the generated route map, so stale types mean `codegen` hasn't run.
+  </Accordion>
+  <Accordion title="Will add overwrite my local changes to a block?">
+    Not silently — the CLI asks before overwriting existing files unless you pass `--overwrite`. Use `diff` first to see exactly what changed between your copy and the registry.
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Add a feature with a block" href="/rc/resources/tutorials/add-a-block">
+    The install workflow end to end — search, view, add, migrate.
+  </Card>
+  <Card title="API Client" href="/rc/tools/api-client">
+    What codegen's route map powers on the frontend.
+  </Card>
+</CardGroup>

package/content/tools/dashboard-sdk.mdx

@@ -0,0 +1,35 @@
+---
+title: "Dashboard SDK"
+description: "The Vite plugin that powers admin and vendor panel extension — file-based routing, virtual modules, and block resolution."
+---
+
+<Note>
+  This reference is being written. The outline below is the intended structure.
+</Note>
+
+<Info>
+  **Not Medusa's admin-vite-plugin.** The dashboard SDK is Mercur's own extension framework for both panels — it scans `src/routes/**/page.tsx` files, generates navigation, and injects everything through `virtual:mercur/*` modules at build time. Medusa's `defineWidgetConfig` / `defineRouteConfig` and widget zones are not part of this model. Start with [Extending Panels](/rc/resources/customization/extending-panels) for the authoring guide; this page covers the plugin's internals and options.
+</Info>
+
+## What it does
+
+File-based routing, virtual route modules, and block resolution for the admin and vendor panels.
+
+## Setup in a host app
+
+Registering `mercurDashboardPlugin` in a Vite app.
+
+## Configuration options
+
+Backend and vendor URLs, i18n, and build-time config.
+
+## Extension entry points
+
+`admin_ui` and `vendor_ui` entry points exported by block packages.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Extending the panels" href="/rc/resources/customization/extending-panels" />
+  <Card title="API client" href="/rc/tools/api-client" />
+</CardGroup>

package/content/user-guide/admin/overview.mdx

@@ -0,0 +1,23 @@
+---
+title: "Admin Panel"
+description: "What marketplace operators do in the Admin Panel — no technical knowledge required."
+---
+
+<Note>
+  This guide is being written. The outline below is the intended structure.
+</Note>
+
+## What you can do here
+
+Manage sellers, configure commissions, monitor orders and payouts, and control marketplace settings.
+
+## Common tasks
+
+Links to the per-area guides as they are added.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Stores" href="/rc/user-guide/admin/stores" />
+  <Card title="Vendor Panel" href="/rc/user-guide/vendor/overview" />
+</CardGroup>

package/content/user-guide/admin/stores.mdx

@@ -0,0 +1,193 @@
+---
+title: "Stores in Mercur Admin Panel"
+sidebarTitle: "Stores"
+mode: "default"
+---
+
+This guide explains how to manage stores in the Mercur Admin Panel.
+
+## View Stores
+
+To view all stores, select “Stores” in the sidebar menu in your panel.
+
+The table shows store details like name, email, status, date and and whether the admin featured the store. Use search, filter, and sort to find a specific store.
+
+One vendor can have multiple stores, each displayed separately in the list.
+
+![Stores (3)](/images/Stores-\(3\).png)
+
+## Create Store
+
+To create a store:
+
+1. Go to “Stores” in the sidebar.
+2. Click on the “Create” button.
+
+This opens a form with two steps: “Details” and “Admin”
+
+### 1. Details Step
+
+In the first “Details” step, you can enter the store general information:
+
+1. Enter “Name” and “Email”
+2. Optionally enter “Handle” and “Phone”. The “Handle” field value appears in the store storefront URL. It creates a human-readable URL and must be unique across all stores, containing only lowercase letters, numbers, and hyphens. If left blank, Mercur generates a handle from the name.
+3. Select “Currency.” Each store can have only one currency.
+4. Once you're done, click the "Continue" button.
+
+![Create Store (3).png](/images/user-guides/admin/stores/2.png)
+
+### 2. Admin Step
+
+In the second “Admin” step, you assign an admin vendor to manage this store. You can select an existing user or invite a new one. As you type, suggestions will appear: select one or add a new email. Once the store is created, the selected user will receive an email invitation to join.
+
+![Create Store (4).png](/images/user-guides/admin/stores/3.png)
+
+Once you create the store, it appears on the list with pending status. The store details entered by the admin during creation can be overwritten by the vendor during onboarding. You can block this depending on the onboarding flow you want.
+
+## Store Details
+
+To view store details:
+
+1. Go to “Stores” in the sidebar.
+2. Choose the store from the list.
+
+This opens the store details page. Here, you can view and edit store details, address, company details, payment details, and access their orders, products, users, and time off.
+
+![Store Details (14)](/images/Store-Details-\(14\).png)
+
+### Edit Store Details
+
+To edit store details:
+
+1. Go to “Stores” in the sidebar.
+2. Choose the store from the list.
+3. Click the icon in the section’s header.
+4. Choose “Edit” from the dropdown.
+5. In the side window that opens, you can edit the store:
+   - Status. There are three statuses: Active, Pending, Inactive. When a store is “Inactive” or “Pending”, their products won’t be visible on the storefront.
+   - Name
+   - Description
+   - Handle
+   - Email
+   - Phone
+   - Website
+   - Featured Store Settings. If checked, the store will be highlighted with a special badge for internal use or promotional purposes.
+   - Media. You can add logo and banner. This media will be visible on the storefront.
+6. Once you’re done, click the “Save” button.
+
+<Warning>
+  Once the currency is set, it cannot be changed.
+</Warning>
+
+<Note>
+  Once the admin edits store details, the vendor is notified in their panel.
+</Note>
+
+![Store Details Edit Store (4)](/images/Store-Details---Edit-Store-\(4\).png)
+
+### Edit Store Address
+
+To edit store address:
+
+1. Go to “Stores” in the sidebar.
+2. Choose the store from the list.
+3. Click the icon in the “Address” header.
+4. Choose “Edit” from the dropdown.
+5. In the side window that opens, you can edit:
+   - Name
+   - Address
+   - Apartment, suite, etc.
+   - Postal Code
+   - City
+   - Country
+   - State
+6. Once you're done, click the “Save” button.
+
+![Store Details Edit Address (3)](/images/Store-Details---Edit-Address-\(3\).png)
+
+### Edit Store Company Details
+
+To edit company details:
+
+1. Go to “Stores” in the sidebar.
+2. Choose the store from the list.
+3. Click the icon in the “Company Details” header.
+4. Choose “Edit” from the dropdown.
+5. In the side window that opens, you can edit:
+   - Company
+   - Registration number
+   - Tax ID
+6. Once you're done, click the “Save” button.
+
+![Store Details Edit Company Details (3)](/images/Store-Details---Edit-Company-Details-\(3\).png)
+
+### Edit Store Payment Details
+
+To edit payment details:
+
+1. Go to “Stores” in the sidebar.
+2. Choose the store from the list.
+3. Click the icon in the “Payment Details” header.
+4. Choose “Edit” from the dropdown.
+5. In the side window, you can edit payment details:
+   1. For all countries except the United States, provide the following details based on your needs:
+      - Account name
+      - IBAN
+      - Account number
+      - SWIFT/BIC
+   2. For United States:
+      - Account name
+      - Account number
+      - ACH routing number
+6. Once you're done, click the “Save” button.
+
+![Store Details Edit Payment Details (3)](/images/Store-Details---Edit-Payment-Details-\(3\).png)
+
+## Users
+
+In the “Users” tab, view all store team members who manage the store. You can add new users by selecting existing ones from your base or inviting new members. You can also remove users from the store.
+
+The user added during store creation is the main admin and cannot be removed. This user is marked with an “Admin” badge.
+
+![Store Details Users (6)](/images/Store-Details---Users-\(6\).png)
+
+### Add New User
+
+To add a new user:
+
+1. Go to “Stores” in the sidebar.
+2. Choose the store from the list.
+3. Select the “Users” tab
+4. Click the “Add” button in the section's header.
+5. In the form that opens add:
+   1. Email. As you type, suggestions will appear; select one or add a new email.
+   2. Role. There are five roles:
+      - Store Administration
+      - Inventory Management
+      - Order Management
+      - Accounting
+      - Support
+6. Once you're done, click the “Save” button.
+
+![Store Details Users (7)](/images/Store-Details---Users-\(7\).png)
+
+## Time Off
+
+In the “Time off” tab, view the store's time off. It specifies the period when the store will be unavailable to receive orders. The vendor can specify one time off period and add a note. During this period, the store’s products will not be visible on the storefront.
+
+![Store Details (15)](/images/Store-Details-\(15\).png)
+
+## Store Request
+
+The vendor can submit a request to create a new store. Once submitted, the store appears on the list with “Pending” status. On the store details page, a block appears at the top with two actions:
+
+- Confirm
+- Reject
+
+You can review the request, make necessary updates, and choose to confirm and publish the store or reject the request. Once confirmed, the store status changes to Active.
+
+<Note>
+  Once the admin confirms or rejects the store creation request, the vendor receives an email.
+</Note>
+
+![Store Details Pending Requested (2)](/images/Store-Details---Pending---Requested-\(2\).png)

package/content/user-guide/vendor/overview.mdx

@@ -0,0 +1,23 @@
+---
+title: "Vendor Panel"
+description: "What sellers do in the Vendor Panel — no technical knowledge required."
+---
+
+<Note>
+  This guide is being written. The outline below is the intended structure.
+</Note>
+
+## What you can do here
+
+Manage products, process orders, configure shipping, track payouts, and complete onboarding.
+
+## Common tasks
+
+Links to the per-area guides as they are added.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Stores" href="/rc/user-guide/vendor/stores" />
+  <Card title="Admin Panel" href="/rc/user-guide/admin/overview" />
+</CardGroup>