@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/references/modules/search.mdx

@@ -1,112 +0,0 @@
----
-title: "Search module"
-description: "The provider-agnostic search module, its document shapes, and the provider contract."
----
-
-The Search module is a **provider abstraction**: it owns no data models and wraps exactly one registered search provider behind three verbs — `index`, `remove`, `search`. Mercur ships a default in-process provider built on [Orama](https://oramasearch.com) that requires zero external infrastructure; operators can swap in Algolia, Meilisearch, or anything else by implementing the same contract.
-
-Both **products** (master catalog entries) and **offers** (per-seller listings with offer-scoped prices) are indexed.
-
-## Document shape
-
-```ts
-interface SearchDoc {
-  id: string
-  type: "product" | "offer"
-  title: string
-  description?: string
-  handle: string
-  thumbnail?: string
-  seller_handle?: string          // offers only
-  collection_id?: string
-  collection?: string
-  category_ids?: string[]
-  categories?: string[]
-  product_id?: string             // offers
-  variant_id?: string             // offers
-  sku?: string                    // offers
-  attribute_tokens: string[]      // facetable: "attr:<handle>:<value_id>"
-  attributes: Record<string, string> // stored label map
-  prices: Record<string, SearchDocPrice> // keyed by region_id, stored not indexed
-}
-```
-
-Prices are **stored, not searched**: each document carries a per-region price map (`calculated_amount`, `original_amount`, `currency_code`), and the provider projects `calculated_price` for the requested region at query time. Suspended sellers' offers and unpublished products are excluded at index time. Attributes flagged `is_filterable` are tokenized into `attribute_tokens` for faceting.
-
-## Query and results
-
-```ts
-interface SearchQueryBase {
-  q?: string
-  limit?: number
-  offset?: number
-  context?: Record<string, unknown>  // pricing/display context, not a filter
-  filters?: Record<string, unknown>  // provider-owned shape
-}
-
-interface SearchResults {
-  hits: SearchDoc[]
-  count: number
-  facets: { collections; categories; attributes } // pre-labelled by the provider
-}
-```
-
-`filters` is an open passthrough — each provider defines its own filter shape. The built-in Orama provider accepts:
-
-```ts
-filters?: {
-  type?: "product" | "offer"
-  collection_ids?: string[]
-  category_ids?: string[]
-  seller_handle?: string
-  attributes?: Record<string, string[]> // attribute handle -> selected value ids
-}
-```
-
-## Service
-
-`SearchModuleService` exposes:
-
-| Method | Behavior |
-| --- | --- |
-| `index(docs)` | Upserts documents into the provider index |
-| `remove(ids)` | Removes documents by ID |
-| `search(query)` | Runs a query against the provider |
-| `getProviderIdentifier()` | Returns the active provider's identifier |
-
-## Provider contract
-
-Implement `AbstractSearchProvider` (exported from the module) and register it via the module's `provider` option. Exactly one provider must be registered — the module throws at boot otherwise. If no provider is configured, the Orama provider registers automatically.
-
-```ts
-abstract class AbstractSearchProvider<TQuery extends SearchQueryBase> {
-  static identifier: string
-  abstract index(docs: SearchDoc[]): Promise<void>
-  abstract remove(ids: string[]): Promise<void>
-  abstract search(query: TQuery): Promise<SearchResults>
-}
-```
-
-<Warning>
-  The built-in Orama provider holds its index **in process memory**. It starts
-  empty, is rebuilt on boot via the reindex event, and does not share state
-  across processes. For multi-instance deployments, use an external provider.
-</Warning>
-
-## Index synchronization
-
-Sync is event-driven — there are no search workflows:
-
-- Subscribers react to product, offer, and seller changes (`search-product-changed`, `search-product-deleted`, `search-offer-changed`, `search-seller-changed`) and reindex or remove the affected documents.
-- A full rebuild runs when the `search.reindex` event (`SEARCH_REINDEX_EVENT`) is emitted; in worker mode the module emits it automatically on application start.
-
-## Related endpoints
-
-`POST /store/search` — the storefront query route. Body: `q`, `limit` (default 12, max 100), `offset`, `region_id` / `country_code` / `province` (pricing context), and the provider-owned `filters`. Responds with `{ hits, count, limit, offset, facets }`. Customer authentication is optional.
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Search integrations" href="/rc/resources/integrations/search" />
-  <Card title="Store API" href="/rc/references/api/store" />
-</CardGroup>

package/content/references/modules/seller.mdx

@@ -1,175 +0,0 @@
----
-title: "Seller module"
-description: "Data models, links, and service methods for the Seller module."
----
-
-The Seller module owns the marketplace vendor domain: the seller entity and its satellite records (professional details, address, payment details), the seller's team (members and pending invites), and the **order group** — the aggregate that binds the per-seller orders created from a single multi-vendor cart.
-
-For the conceptual introduction, see [Sellers](/rc/learn/sellers), [Seller members](/rc/learn/seller-members), and [Order groups](/rc/learn/order-groups).
-
-## Data models
-
-### `Seller`
-
-Table `seller`, ID prefix `sel`.
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `id` | text | Primary key |
-| `name` | text | Unique, searchable |
-| `handle` | text | Unique, URL-friendly; auto-generated from `name` when omitted |
-| `email` | text | Unique, searchable |
-| `phone` | text | Nullable |
-| `description` | text | Nullable |
-| `logo` | text | Nullable |
-| `banner` | text | Nullable |
-| `website_url` | text | Nullable |
-| `external_id` | text | Nullable; unique when set |
-| `currency_code` | text | The seller's single operating currency |
-| `status` | enum | `SellerStatus`, default `pending_approval` |
-| `status_reason` | text | Nullable |
-| `approved_at` | dateTime | Nullable |
-| `rejected_at` | dateTime | Nullable |
-| `is_premium` | boolean | Default `false`; operator-set only |
-| `closed_from` / `closed_to` | dateTime | Nullable; scheduled closure window |
-| `closure_note` | text | Nullable |
-| `metadata` | json | Nullable |
-
-Relations: `professional_details`, `address`, and `payment_details` (one-to-one, deleted with the seller), `members` (many-to-many through `SellerMember`), `member_invites` (one-to-many, deleted with the seller).
-
-### `ProfessionalDetails`
-
-Table `professional_details`, ID prefix `selprodet`. Presence of this record marks the seller as a registered business.
-
-| Field | Type |
-| --- | --- |
-| `corporate_name` | text, nullable |
-| `registration_number` | text, nullable |
-| `tax_id` | text, nullable |
-
-### `SellerAddress`
-
-Table `seller_address`, ID prefix `seladdr`. Fields: `name`, `company`, `first_name`, `last_name`, `address_1`, `address_2`, `city`, `country_code`, `province`, `postal_code`, `phone`, `metadata` — all nullable.
-
-### `PaymentDetails`
-
-Table `payment_details`, ID prefix `selpaydet`. Fields: `country_code`, `holder_name`, `bank_name`, `iban`, `bic`, `routing_number`, `account_number` — all nullable.
-
-### `Member`
-
-Table `member`, ID prefix `mem`. A member is a dashboard user that can belong to one or more sellers.
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `email` | text | Unique, searchable |
-| `first_name` / `last_name` | text | Nullable |
-| `locale` | text | Nullable |
-| `is_active` | boolean | Default `true` |
-| `metadata` | json | Nullable |
-
-### `SellerMember`
-
-Table `seller_member`, ID prefix `selmem`. Pivot between `Seller` and `Member`; unique on (`seller_id`, `member_id`).
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `role_id` | text | Nullable; resolved against the RBAC roles module |
-| `is_owner` | boolean | Default `false` |
-| `metadata` | json | Nullable |
-
-### `MemberInvite`
-
-Table `member_invite`, ID prefix `meminv`. Unique on (`email`, `seller_id`) while unaccepted.
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `email` | text | Searchable |
-| `token` | text | Signed JWT |
-| `accepted` | boolean | Default `false` |
-| `expires_at` | dateTime | Derived from `invite_valid_duration` |
-| `role_id` | text | Role assigned on acceptance |
-| `metadata` | json | Nullable |
-
-### `OrderGroup`
-
-Table `order_group`, ID prefix `og`. Created when a multi-vendor cart completes.
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `display_id` | autoincrement | Shopper-facing number |
-| `cart_id` | text | The originating cart |
-| `customer_id` | text | Nullable |
-| `seller_count` | number | Computed |
-| `total` | bigNumber | Computed across child orders |
-
-## Enums
-
-```ts
-enum SellerStatus {
-  OPEN = "open",
-  PENDING_APPROVAL = "pending_approval",
-  SUSPENDED = "suspended",
-  TERMINATED = "terminated",
-}
-
-enum SellerRole {
-  SELLER_ADMINISTRATION = "role_seller_administration",
-  INVENTORY_MANAGEMENT = "role_seller_inventory_management",
-  ORDER_MANAGEMENT = "role_seller_order_management",
-  ACCOUNTING = "role_seller_accounting",
-  SUPPORT = "role_seller_support",
-}
-```
-
-## Links
-
-The seller is the anchor of the marketplace graph. Nearly every seller-scoped resource is connected through a module link rather than a foreign key:
-
-| Linked entity | Cardinality | Purpose |
-| --- | --- | --- |
-| `Product.product` | many-to-many (`product_seller`) | Selling-eligibility allowlist for [master products](/rc/references/modules/product-edit) |
-| `Order.order` | one seller — many orders | Per-seller child orders |
-| `Payout.payout` | one seller — many payouts | Settlements |
-| `Payout.payoutAccount` | one-to-one | The seller's provider account |
-| `Pricing.priceList` | one seller — many lists | Vendor price lists |
-| `Promotion.promotion` / `Promotion.campaign` | one seller — many | Vendor promotions and campaigns |
-| `Inventory.inventoryItem` | one seller — many items | Vendor inventory |
-| `StockLocation.stockLocation` | one seller — many | Vendor locations |
-| `Fulfillment.shippingProfile` / `shippingOption` / `fulfillmentSet` / `serviceZone` | one seller — many | Vendor shipping setup |
-| `Customer.customer` / `customerGroup` | many-to-many / one seller — many | Vendor customer base |
-| `Product.productCategory` | many-to-many | Categories a seller may sell in |
-
-Order groups carry two additional links: a read-only link to the originating `Cart` (via `cart_id`) and a list link to the child `Order` records (table `order_group_order`). The `SellerMember.role_id` field is a read-only link into the RBAC roles module.
-
-## Service
-
-`SellerModuleService` extends `MedusaService` with auto-generated CRUD for all models above, plus:
-
-| Method | Behavior |
-| --- | --- |
-| `createSellers(data)` / `updateSellers(data)` | Validates the handle and auto-generates it from `name` when missing |
-| `upsertMembers(data)` | Dedupes by email, creates missing members, backfills empty names; returns members in input order |
-| `createMemberInvites(data)` | Rejects emails that already belong to the seller; issues a JWT token with an expiry |
-| `validateMemberInviteToken(token)` | Verifies the JWT and rejects accepted or expired invites |
-| `listOrderGroups` / `listAndCountOrderGroups` / `retrieveOrderGroup` | Custom repository-backed reads that resolve the computed `seller_count` and `total` fields |
-
-## Module options
-
-| Option | Type | Default | Purpose |
-| --- | --- | --- | --- |
-| `invite_valid_duration` | number (seconds) | 7 days | Member invite lifetime |
-| `jwt_secret` | string | project `http.jwtSecret` | Signs invite tokens |
-| `vendor_url` | string | `MERCUR_VENDOR_URL` env var | Vendor dashboard base URL used in invite links |
-
-## Related endpoints
-
-- [Admin API — sellers, members, order groups](/rc/references/api/admin)
-- [Vendor API — sellers, members](/rc/references/api/vendor)
-- [Store API — public seller storefronts](/rc/references/api/store)
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Commission module" href="/rc/references/modules/commission" />
-  <Card title="Payout module" href="/rc/references/modules/payout" />
-</CardGroup>

package/content/references/panel-extension-api.mdx

@@ -1,337 +0,0 @@
----
-title: "Panel Extension API"
-description: "The file-based helpers for extending the admin and vendor panels — defineWidgetConfig, defineNavigationConfig, defineCustomFieldsConfig, createFormHelper — and the exact props passed to every component you supply."
----
-
-This is the technical contract for the panel extension API.
-Where the [Extend forms and tables](/rc/resources/tutorials/extend-forms-and-tables),
-[Add a widget](/rc/resources/tutorials/add-a-widget), and
-[Customize navigation](/rc/resources/tutorials/customize-navigation) tutorials
-walk through *building* an extension, this page documents the exact config shape
-of each helper and — most importantly — **the props each `component` you pass in
-receives at render time**.
-
-<Info>
-  **Separate apps, no `surface` field.** Admin (`@mercurjs/admin`, port 7000) and
-  vendor (`@mercurjs/vendor`, port 7001) are separate Vite apps. A file dropped
-  under a panel's `src/` targets *that* panel — the folder you author in *is* the
-  surface. The helpers are the same in both; import them from
-  `@mercurjs/dashboard-sdk` (config helpers) and `@mercurjs/dashboard-shared`
-  (`createFormHelper`).
-</Info>
-
-## Typed targets (register once)
-
-Zone ids, nav item ids, models, and built-in field ids are typed per panel from a
-generated `extension-targets.d.ts`. Reference it once per host app so every
-extension file type-checks with no per-file import:
-
-```typescript apps/vendor/src/extension-targets.d.ts
-/// <reference types="@mercurjs/vendor/extension-targets" />
-```
-
-```typescript apps/admin-test/src/extension-targets.d.ts
-/// <reference types="@mercurjs/admin/extension-targets" />
-```
-
-A wrong `zone`, `model`, or nav `id` fails `tsc` (`bun run lint`) rather than
-silently no-op'ing at runtime.
-
----
-
-## `defineWidgetConfig`
-
-A widget is a React component attached to a named zone on a built-in page. The
-placement (`before | after | replace`) is the last segment of the zone id.
-
-```tsx apps/vendor/src/widgets/product-list-banner.tsx
-import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
-
-export const config = defineWidgetConfig({
-  zone: "product.list.before", // WidgetZoneId — <domain>.<view>[.<slot>].<before|after|replace>
-})
-
-export default ProductListBanner
-```
-
-### Config
-
-| Field  | Type                            | Description                                                                 |
-| ------ | ------------------------------- | --------------------------------------------------------------------------- |
-| `zone` | `WidgetZoneId \| WidgetZoneId[]` | Target zone(s). Placement is the suffix. Multiple widgets stack in order.    |
-| `id`   | `string` (optional)             | Stable id; derived from the file path at build time when omitted.           |
-
-### Component props
-
-The widget component receives a single prop:
-
-| Prop   | Type      | Description                                                                                |
-| ------ | --------- | ----------------------------------------------------------------------------------------- |
-| `data` | `unknown` | The zone's contextual entity — e.g. the loaded product on a `product.detail.*` zone. Undefined on list/public zones that have no single entity. |
-
-```tsx
-const ProductDetailNote = ({ data }: { data?: HttpTypes.AdminProduct }) => (
-  <Container>{data?.title}</Container>
-)
-```
-
-<Note>
-  The public `login.logo` / `login.before` / `login.after` zones render before
-  authentication and receive no `data`.
-</Note>
-
----
-
-## `defineNavigationConfig`
-
-Reorder, hide, relabel, or re-parent **built-in** sidebar items. Single
-host-owned file — blocks cannot contribute nav overrides.
-
-```ts apps/vendor/src/_navigation.ts
-import { defineNavigationConfig } from "@mercurjs/dashboard-sdk"
-
-export default defineNavigationConfig({
-  items: [
-    { id: "orders", rank: 0 },
-    { id: "price-lists", hidden: true },
-    { id: "payouts", label: "settlements" },
-    { id: "categories", nested: null, rank: 1 },
-    { id: "campaigns", nested: "orders" },
-  ],
-})
-```
-
-### `NavItemOverride`
-
-| Field    | Type                       | Description                                                                    |
-| -------- | -------------------------- | ------------------------------------------------------------------------------ |
-| `id`     | `NavItemId`                | Built-in item to override (top-level or nested). Typed against the panel registry. |
-| `rank`   | `number` (optional)        | Order within the item's parent (or among top-level items).                     |
-| `hidden` | `boolean` (optional)       | Remove from the sidebar (route may still be directly reachable).               |
-| `label`  | `string` (optional)        | i18n key or literal replacing the item's label.                                |
-| `icon`   | `ComponentType` (optional) | Icon component replacing the item's icon (from `@medusajs/icons`).             |
-| `nested` | `NavParentId \| null` (optional) | Re-parent under a built-in parent id; `null` promotes a nested item to top level. |
-
-There is no `component` prop here — navigation overrides reshape existing items
-only.
-
----
-
-## `defineCustomFieldsConfig`
-
-The model-scoped surface. One file per model adds form fields, section displays,
-section actions, and list-table columns. Import
-`createFormHelper` from `@mercurjs/dashboard-shared` to turn a Zod schema into an
-input type + validation.
-
-```tsx apps/vendor/src/custom-fields/product.tsx
-import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
-import { createFormHelper } from "@mercurjs/dashboard-shared"
-
-type ProductWithMeta = { metadata?: Record<string, unknown> }
-const form = createFormHelper<ProductWithMeta>()
-
-export default defineCustomFieldsConfig({
-  model: "product",
-  link: "brand", // string | string[] — module link(s) fetched alongside the entity
-  forms: [/* ... */],
-  displays: [/* ... */],
-  list: {/* ... */},
-})
-```
-
-### Top-level config
-
-| Field      | Type                     | Description                                                              |
-| ---------- | ------------------------ | ------------------------------------------------------------------------ |
-| `model`    | `CustomFieldModel`       | Target model (start with `"product"`). Typed against `CustomFieldsRegistry`. |
-| `link`     | `string \| string[]`     | Module link(s) fetched alongside the entity; their data is available to columns and displays via the `+link.*` fetch. |
-| `forms`    | `CustomFormEntry[]`      | Fields injected into built-in create/edit/onboarding forms.              |
-| `displays` | `CustomDisplayEntry[]`   | Field replace/remove/add + `ActionMenu` actions on detail sections.      |
-| `list`     | `CustomListExtension`    | Columns, bulk actions, filters, view defaults on the model's list table. |
-
-### `forms[]` — form fields
-
-```tsx
-forms: [
-  {
-    zone: "edit",         // CustomFormZone — "create" | "edit" | "organize" | "attributes" | "onboarding"
-    tab: "general",       // TabbedForm tab id, or wizard step id for zone: "onboarding"
-    fields: {
-      erp_id: form.define({
-        validation: form.string().nullish(), // Zod → input type + validation
-        defaultValue: (data) => (data?.metadata?.erp_id as string) ?? "",
-        label: "ERP ID",
-        description: "External system identifier",
-        placeholder: "ERP-000",
-        component: MyErpInput, // optional custom render
-      }),
-    },
-  },
-]
-```
-
-Each field is a `CustomFormField`:
-
-| Field          | Type                                     | Description                                                       |
-| -------------- | ---------------------------------------- | ----------------------------------------------------------------- |
-| `validation`   | Zod schema                               | Drives both the default input type and validation.                |
-| `defaultValue` | `unknown \| ((data) => unknown)`         | Static value or a resolver from the loaded entity.                |
-| `label`        | `string` (optional)                      | Field label.                                                      |
-| `description`  | `string` (optional)                      | Help text below the input.                                        |
-| `placeholder`  | `string` (optional)                      | Input placeholder.                                                |
-| `component`    | `ComponentType` (optional)               | Custom render; falls back to a default input for the Zod type.    |
-
-<Warning>
-  **Form-field `component` receives no props.** It is rendered as `<Component />`
-  inside the field's `additional_data.<field>` React Hook Form context. Read and
-  write the value with RHF's `useFormContext()` / `useController()`, and render
-  through the mandated `Form.Field → Form.Item` chain — do not use a raw
-  `Controller`. Values live in form state under `additional_data`; in the MVP,
-  `product` custom fields persist onto the product's `metadata`.
-</Warning>
-
-### `displays[]` — detail sections
-
-```tsx
-displays: [
-  {
-    zone: "general", // CustomFieldsRegistry displayZones — an existing detail section id
-    fields: [
-      { id: "erp_id", component: ErpRow },           // ADD (unknown id → new read-only row)
-      { id: "status", component: BrandedStatusBadge }, // REPLACE a built-in field's render
-      { id: "created_by", component: null },           // REMOVE a built-in field
-    ],
-    actions: [
-      { rank: 0, component: SyncErpAction },            // add to the section's ActionMenu
-    ],
-  },
-]
-```
-
-`fields[]` is `CustomDisplayField`:
-
-| Field       | Type                                    | Description                                                                            |
-| ----------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
-| `id`        | `displayFieldIds \| (string & {})`      | Built-in field id (autocompletes) → replace/remove; any other string → add a new row.  |
-| `component` | `ComponentType<{ data? }> \| null`      | Render component, or `null` to remove a built-in field.                                |
-
-**Display field `component` props:**
-
-| Prop   | Type      | Description                        |
-| ------ | --------- | ---------------------------------- |
-| `data` | `unknown` | The loaded detail entity, **including any `link`ed module data**. If the config declares `link: "brand"`, read it off `data.brand` here. |
-
-```tsx
-// with `link: "brand"` on the config, the linked module data rides on `data`
-const BrandRow = ({ data }: { data?: { brand?: { name: string } } }) => (
-  <Text>{data?.brand?.name}</Text>
-)
-```
-
-`actions[]` is `SectionAction` (the same shape as list `bulkActions`):
-
-| Field       | Type                            | Description                                                       |
-| ----------- | ------------------------------- | ----------------------------------------------------------------- |
-| `rank`      | `number` (optional)             | Position within the section's `ActionMenu`.                       |
-| `component` | `ComponentType<{ data? }>`      | Owns its own label, icon, group placement, and `onClick`.         |
-
-**Section-action `component` props:**
-
-| Prop   | Type      | Description                                                              |
-| ------ | --------- | ----------------------------------------------------------------------- |
-| `data` | `unknown` | The loaded detail entity, **including any `link`ed module data** (e.g. `data.brand`). |
-
-### `list` — list table
-
-```tsx
-list: {
-  columns: [
-    { id: "title", component: ({ value }) => <strong>{value}</strong> }, // override a cell
-    { id: "brand_name", header: "Brand", component: ({ row }) => row.brand?.name }, // add (from link)
-  ],
-  bulkActions: [{ rank: 0, component: ArchiveBulkAction }],
-  filters: [/* add / remove list filters */],
-  viewDefaults: {
-    columnVisibility: { created_at: false }, // hide a column
-    columnOrder: ["title", "sku", "erp_id"],
-  },
-}
-```
-
-`columns[]` is `CustomColumn`:
-
-| Field       | Type                                       | Description                                              |
-| ----------- | ------------------------------------------ | -------------------------------------------------------- |
-| `id`        | `string`                                   | Column id — matches a built-in column to override, or adds a new one. |
-| `header`    | `string` (optional)                        | Column header text (for added columns).                 |
-| `component` | `ComponentType<{ row?, value? }>` (optional) | Cell renderer.                                          |
-
-**Column `component` props:**
-
-| Prop    | Type      | Description                                               |
-| ------- | --------- | -------------------------------------------------------- |
-| `row`   | `unknown` | The full row entity (including `link`ed module data).    |
-| `value` | `unknown` | The cell value for this column id, when derivable.       |
-
-`bulkActions[]` is `SectionAction` (`{ rank?, component }`, component props `{ data? }`).
-
-<Note>
-  **Bulk-action rendering is deferred in the MVP.** `bulkActions` are accepted and
-  surfaced by the config but not yet mounted into the list toolbar.
-</Note>
-
-<Warning>
-  **Vendor product list is field-constrained.** The vendor `product` list must use
-  the curated fields from `useProductTableQuery` — the SDK merges `link` fetches
-  with the `+`/`-` convention, never bare fields, or the list 500s. You never
-  hand-write the field list; the `link` declaration drives it.
-</Warning>
-
----
-
-## `createFormHelper`
-
-`createFormHelper<T>()` returns Medusa's zod surface for describing field
-validation and value types:
-
-```ts
-const form = createFormHelper<ProductWithMeta>()
-
-form.define({ validation, defaultValue?, label?, description?, placeholder?, component? })
-form.string() / form.number() / form.boolean() / form.date()
-form.array() / form.object() / form.null() / form.nullable() / form.coerce
-```
-
-The generated registry types the **target** (which zone/tab/field ids exist); the
-Zod `validation` types the **value**. The two compose — codegen types the address,
-Zod types the payload.
-
----
-
-## Persistence
-
-<Warning>
-  **The MVP is a UI surface only.** Custom fields render, validate, and display
-  through the built-in forms/sections/tables — there is no generic core-side write
-  path. For `product`, values are submitted under `additional_data` and persisted
-  onto `metadata`. To store data for other models, wire your own route/workflow or
-  use the backend [Custom Fields module](/rc/resources/customization/custom-fields).
-</Warning>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Extend forms and tables" href="/rc/resources/tutorials/extend-forms-and-tables">
-    Step-by-step build with `defineCustomFieldsConfig`.
-  </Card>
-  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
-    Inject a component into a zone.
-  </Card>
-  <Card title="Customize navigation" href="/rc/resources/tutorials/customize-navigation">
-    Reorder and hide sidebar items.
-  </Card>
-  <Card title="Custom Fields module" href="/rc/references/modules/custom-fields">
-    The backend storage layer.
-  </Card>
-</CardGroup>

package/content/references/workflows/cart/add-seller-shipping-method-to-cart.mdx

@@ -1,48 +0,0 @@
----
-title: "addSellerShippingMethodToCartWorkflow"
-description: "Add shipping methods to a cart, replacing only the same seller's existing methods."
----
-
-Seller-aware variant of Medusa's `addShippingMethodToCartWorkflow`. Validates the requested options against the cart and their calculated prices, then swaps shipping methods per seller: existing methods belonging to the sellers whose options are being added are removed, while other sellers' methods stay untouched — so a multi-seller cart keeps one shipping method per seller. Refreshes cart items afterwards and emits `cart.updated`. Triggered by `POST /store/carts/:id/shipping-methods`.
-
-## Usage
-
-```ts
-import { addSellerShippingMethodToCartWorkflow } from "@mercurjs/core/workflows"
-
-await addSellerShippingMethodToCartWorkflow(container).run({
-  input: {
-    cart_id: "cart_123",
-    options: [{ id: "so_123" }],
-  },
-})
-```
-
-## Input
-
-<ParamField body="cart_id" type="string" required>The cart to add shipping methods to.</ParamField>
-
-<ParamField body="options" type="object[]" required>
-  Shipping options to add as methods.
-
-  <Expandable title="properties">
-    <ParamField body="id" type="string" required>The shipping option ID; must have a calculated price for the cart.</ParamField>
-    <ParamField body="data" type="object">Custom method data validated by the fulfillment provider.</ParamField>
-  </Expandable>
-</ParamField>
-
-<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
-
-## Result
-
-<ResponseField name="result" type="void">No return value; the cart's shipping methods are replaced per seller as a side effect.</ResponseField>
-
-## Hooks
-
-- `validate` — runs after the cart is loaded with `{ input, cart }`.
-
-```ts
-addSellerShippingMethodToCartWorkflow.hooks.validate(async ({ input, cart }) => {
-  // throw to reject the shipping method
-})
-```