@mercurjs/docs 2.3.8-canary.2 → 2.3.8-canary.4

package/content/platform/store/reference/workflows.mdx

@@ -1,35 +1,315 @@
 ---
-title: "Workflows"
+title: "Seller module workflows"
 sidebarTitle: "Workflows"
-description: "Seller and member workflows, service methods, and events."
+description: "Every store, lifecycle, business-detail, and team workflow in the Seller module, with inputs, hooks, and events."
 ---
 
-This reference lists the workflows, service methods, and events for the Store
-domain. Import workflows from `@mercurjs/core/workflows` and run them against the
-Medusa container.
+This reference lists every workflow that writes Seller module data. Import them from `@mercurjs/core/workflows` and run them against the Medusa container: `await workflow(container).run({ input })`. Workflows roll back their completed steps when a later step fails.
 
-## Seller workflows
+```ts
+import { approveSellerWorkflow } from "@mercurjs/core/workflows"
 
-| Workflow | Input | Purpose |
+await approveSellerWorkflow(container).run({
+  input: { seller_id: "sel_01JD8Q1234567" },
+})
+```
+
+Workflows that take `additional_data` pass it to their hooks. Register a hook handler with `workflow.hooks.<hookName>(handler)`.
+
+## createSellersWorkflow
+
+Creates one or more stores, links each to the default region plus `region_ids`, and invites one member per store with `role_seller_administration`. Returns `SellerDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `sellers` | `CreateSellerDTO & { member, region_ids? }[]` | Store fields; `status` defaults to `pending_approval` |
+| `sellers[].member` | `{ email: string }` | Required, the address that gets the invite |
+| `sellers[].region_ids` | `string[]` | Optional, regions besides the default one |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `validate` (`{ input }`), `sellersCreated` (`{ sellers, additional_data }`)
+- **Events**: `seller.created` per store, `member_invite.created` per invite
+
+## createSellerAccountWorkflow
+
+Creates one store in `pending_approval` and adds a member as its owner with `role_seller_administration`. Returns `SellerDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `auth_identity_id` | `string` | The auth identity to attach the member to |
+| `seller` | `CreateSellerDTO` | Store fields; `status` is forced to `pending_approval` |
+| `member_id` | `string` | Optional, an existing member to make owner |
+| `member_email` | `string` | Used when `member_id` is absent to upsert a member |
+| `first_name`, `last_name` | `string` | Optional, set on a new member |
+| `address` | `UpdateSellerAddressDTO` | Optional, written through `updateSellerAddressWorkflow` |
+| `professional_details` | `UpdateProfessionalDetailsDTO` | Optional |
+| `payment_details` | `UpdatePaymentDetailsDTO` | Optional |
+| `region_ids` | `string[]` | Optional, regions besides the default one |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `validate` (`{ input }`), `sellerAccountCreated` (`{ seller, member_id, additional_data }`)
+- **Events**: `seller.created`
+
+## updateSellersWorkflow
+
+Updates every store that matches `selector` with the same `update`. Returns `SellerDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `selector` | `Record<string, unknown>` | Filters, such as `{ id: "sel_01JD8Q1234567" }` |
+| `update` | `UpdateSellerDTO` | Fields to set |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellersUpdated` (`{ sellers, additional_data }`)
+- **Events**: `seller.updated` per store
+
+## deleteSellersWorkflow
+
+Soft deletes stores by id. Compensation restores them.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | Seller ids |
+
+- **Hooks**: none
+- **Events**: `seller.deleted` per store
+
+## approveSellerWorkflow
+
+Moves a `pending_approval` store to `open`, clears `status_reason`, and sets `approved_at` if it’s empty.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to approve |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerApproved` (`{ seller_id, additional_data }`)
+- **Events**: `seller.approved`
+
+## suspendSellerWorkflow
+
+Moves a `pending_approval` or `open` store to `suspended`, saves `reason` in `status_reason`, and sets `rejected_at` if it’s empty.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to suspend |
+| `reason` | `string` | Optional |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerSuspended` (`{ seller_id, additional_data }`)
+- **Events**: `seller.suspended`
+
+## unsuspendSellerWorkflow
+
+Moves a `suspended` store to `open` and clears `status_reason`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to reopen |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerUnsuspended` (`{ seller_id, additional_data }`)
+- **Events**: `seller.unsuspended`
+
+## terminateSellerWorkflow
+
+Moves a `pending_approval` or `suspended` store to `terminated` and saves `reason` in `status_reason`. Fails for an `open` store.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to terminate |
+| `reason` | `string` | Optional |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerTerminated` (`{ seller_id, additional_data }`)
+- **Events**: `seller.terminated`
+
+## unterminateSellerWorkflow
+
+Moves a `terminated` store to `suspended` and clears `status_reason`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store to restore |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `sellerUnterminated` (`{ seller_id, additional_data }`)
+- **Events**: `seller.unterminated`
+
+## linkSellerRegionsWorkflow
+
+Adds and removes store region links in one run. Fails if a region or seller doesn’t exist, or if a store would be left with no region.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `add` | `{ seller_id, region_id }[]` | Optional, links to create |
+| `remove` | `{ seller_id, region_id }[]` | Optional, links to dismiss |
+
+- **Hooks**: none
+- **Events**: none
+
+## updateSellerAddressWorkflow
+
+Creates or updates a store’s `SellerAddress`. Returns `SellerAddressDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `data` | `UpdateSellerAddressDTO` | Address fields |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `addressUpdated` (`{ address, additional_data }`)
+- **Events**: none
+
+## updateSellerProfessionalDetailsWorkflow
+
+Creates or updates a store’s `ProfessionalDetails`. Returns `ProfessionalDetailsDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `data` | `UpdateProfessionalDetailsDTO` | `corporate_name`, `registration_number`, `tax_id` |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `professionalDetailsUpdated` (`{ professional_details, additional_data }`)
+- **Events**: none
+
+## deleteSellerProfessionalDetailsWorkflow
+
+Deletes a store’s `ProfessionalDetails`, if it has any.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `professionalDetailsDeleted` (`{ seller_id, additional_data }`)
+- **Events**: none
+
+## updateSellerPaymentDetailsWorkflow
+
+Creates or updates a store’s `PaymentDetails`. Returns `PaymentDetailsDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `data` | `UpdatePaymentDetailsDTO` | Bank account fields |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `paymentDetailsUpdated` (`{ payment_details, additional_data }`)
+- **Events**: none
+
+## inviteSellerWorkflow
+
+Sends an email that invites someone to register a new store. It creates a notification with the template `newSellerInvitation` on the `email` channel, and writes no Seller module records.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `email` | `string` | The prospective seller |
+| `registration_url` | `string` | Optional, the link in the email’s button |
+
+- **Hooks**: none
+- **Events**: none
+
+## createMemberInvitesWorkflow
+
+Creates team invites with signed tokens. Fails if an email already belongs to the store. Returns `MemberInviteDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `[].seller_id` | `string` | The store |
+| `[].email` | `string` | The invitee |
+| `[].role_id` | `string` | A `SellerRole` value |
+
+The input is an array of invites, not an object.
+
+- **Hooks**: none
+- **Events**: `member_invite.created` per invite
+
+## resendMemberInviteWorkflow
+
+Deletes an invite and creates a replacement with the same email and role, a new token, and a new expiry. Returns `MemberInviteDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `invite_id` | `string` | The invite to replace |
+| `seller_id` | `string` | The store that owns it |
+
+- **Hooks**: none
+- **Events**: `member_invite.created`
+
+## deleteMemberInviteWorkflow
+
+Deletes an invite.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `invite_id` | `string` | The invite to delete |
+
+- **Hooks**: none
+- **Events**: none
+
+## acceptMemberInviteWorkflow
+
+Validates an invite token, upserts the member by email, creates the membership with the invite’s role, and deletes the invite. The member becomes owner when the store has no owner yet. Returns `MemberDTO`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `invite_token` | `string` | The token from the invite |
+| `auth_identity_id` | `string` | The invitee’s auth identity |
+| `member_id` | `string` | Optional; when set, the auth identity isn’t updated |
+| `first_name`, `last_name` | `string` | Optional, set on a new member |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
+
+- **Hooks**: `validate` (`{ input, invite }`), `memberInviteAccepted` (`{ member, invite, additional_data }`)
+- **Events**: `member_invite.accepted`
+
+## addSellerMemberWorkflow
+
+Adds an existing member to a store. Returns the `SellerMember`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | The store |
+| `member_id` | `string` | The existing member |
+| `role_id` | `string` | A `SellerRole` value |
+
+- **Hooks**: none
+- **Events**: `seller_member.created`
+
+## updateMemberRoleWorkflow
+
+Changes the role on a membership. Fails for the owner membership.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `createSellersWorkflow` | `{ sellers[], additional_data? }` | Create stores with defaults |
-| `updateSellersWorkflow` | `{ selector, update }` | Update store fields |
-| `deleteSellersWorkflow` | `{ ids[] }` | Delete stores |
-| `approveSellerWorkflow` | `{ seller_id, additional_data? }` | `pending_approval` → `open` |
-| `suspendSellerWorkflow` | `{ seller_id }` | `open` → `suspended` |
-| `unsuspendSellerWorkflow` | `{ seller_id }` | `suspended` → `open` |
-| `terminateSellerWorkflow` | `{ seller_id }` | → `terminated` (irreversible) |
+| `seller_member_id` | `string` | The membership id (`selmem_…`) |
+| `role_id` | `string` | A `SellerRole` value |
+
+- **Hooks**: none
+- **Events**: `seller_member.updated`
+
+## removeSellerMemberWorkflow
+
+Deletes a membership and keeps the `Member` record. Fails for the owner membership.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_member_id` | `string` | The membership id |
+| `seller_id` | `string` | The store, included in the event payload |
+
+- **Hooks**: none
+- **Events**: `seller_member.deleted`
+
+## updateMemberWorkflow
 
-## Member workflows
+Updates the profile of every member that matches `selector`. Returns `MemberDTO[]`.
 
-| Workflow | Input | Purpose |
+| Input | Type | Description |
 | --- | --- | --- |
-| `inviteSellerWorkflow` | `{ email, seller_id }` | Create + send a member invite |
-| `acceptMemberInviteWorkflow` | `{ token }` | Accept an invite, link the member |
-| `addSellerMemberWorkflow` | `{ seller_id, member }` | Add a member directly |
-| `removeSellerMemberWorkflow` | `{ seller_id, member_id }` | Revoke access |
-| `updateMemberRoleWorkflow` | `{ id, role_id }` | Change a member's role |
+| `selector` | `Record<string, unknown>` | Filters, such as `{ id: "mem_01JD8Q1234567" }` |
+| `update` | `{ first_name?, last_name?, locale? }` | Profile fields |
+| `additional_data` | `Record<string, unknown>` | Optional, passed to hooks |
 
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/store/reference/service). To run side effects when
-a store changes, see the [Event reference](/platform/store/reference/events).
+- **Hooks**: `membersUpdated` (`{ members, additional_data }`)
+- **Events**: none

package/content/references/panel-extensions/layouts.mdx

@@ -0,0 +1,169 @@
+---
+title: "Layouts and layers"
+sidebarTitle: "Layouts and layers"
+description: "How extensions from plugins and your project stack, how a page exposes its sections, and how to hide, reorder, replace or wrap what a page renders."
+---
+
+Every panel extension comes from an ordered list of **layers**:
+
+1. `@mercurjs/admin` or `@mercurjs/vendor` itself,
+2. each plugin in `medusa-config` `plugins` order, from its built `.medusa/server/src/<admin|vendor>/index.mjs`,
+3. your Medusa project's `src/admin` or `src/vendor` folder (next to `medusa-config.ts`),
+4. the panel app's own `src` folder.
+
+A later layer wins. A route at a path an earlier layer declared replaces it, a widget with the same `id`
+replaces it, a translation key overrides it, and a layout preference overrides it field by field. Every
+layer uses the same folders: `routes/`, `widgets/`, `custom-fields/`, `layouts/`, `i18n/` and a
+`_layouts.ts` file.
+
+## Pages expose named entries
+
+A detail or list page renders a `LayoutComposer`. It names the zone widgets target, the layout it uses,
+and gives each section a stable entry id:
+
+```tsx
+import { CORE_LAYOUT_IDS } from "@mercurjs/dashboard-sdk"
+import { LayoutComposer, detailPageDefaultEntries } from "@mercurjs/dashboard-shared"
+
+<LayoutComposer
+  widgetsZonePrefix="product.detail"
+  preferredLayoutId={CORE_LAYOUT_IDS.TWO_COLUMN}
+  data={product}
+  sections={{
+    main: (
+      <>
+        <LayoutComposer.Entry id="ProductGeneralSection">
+          <ProductGeneralSection product={product} />
+        </LayoutComposer.Entry>
+        {detailPageDefaultEntries(product)}
+      </>
+    ),
+    side: (
+      <LayoutComposer.Entry id="ProductOrganizationSection">
+        <ProductOrganizationSection product={product} />
+      </LayoutComposer.Entry>
+    ),
+  }}
+/>
+```
+
+The page's own sections become entries `core:ProductGeneralSection`, `core:MetadataSection` and so on;
+widgets become `widget:<id>`. Use the same component on your own pages and the build emits their zones and
+entry ids into `extension-targets.d.ts`, so the next layer gets autocompletion for them.
+
+## Place a widget
+
+`zone` is the page prefix or one of its sections. `section` and `order` place the widget among the page's
+entries; core entries sit at order `0`, so a negative order renders before them and no order renders after.
+
+```tsx
+export const config = defineWidgetConfig({
+  zone: "product.detail",
+  id: "seller-offers",
+  section: "side",
+  order: -1,
+})
+```
+
+`replace` takes the slot of a page entry. The widget receives `renderDefault` to render what it replaced:
+
+```tsx
+export const config = defineWidgetConfig({
+  zone: "product.detail",
+  id: "general-with-seller",
+  replace: "core:ProductGeneralSection",
+})
+
+export default function GeneralWithSeller({ data, renderDefault }) {
+  return (
+    <>
+      {renderDefault?.()}
+      <SellerBadge product={data} />
+    </>
+  )
+}
+```
+
+The legacy `product.detail.side.before` and `.after` zones still work and map to the first and last
+position of that section.
+
+## Hide, reorder and move entries: `_layouts.ts`
+
+A layer's `_layouts.ts` holds per-zone preferences that apply to everyone. The sidebars are zones too
+(`nav.main`, `nav.settings`) with `nav:<path>` entries, which replaces `_navigation.ts`.
+
+```ts
+import { defineLayoutPreferences } from "@mercurjs/dashboard-sdk"
+import { Tag } from "@medusajs/icons"
+
+export default defineLayoutPreferences({
+  "product.detail": {
+    entries: {
+      "core:ProductMediaSection": { hidden: true },
+      "widget:seller-offers": { section: "main", order: 1 },
+    },
+  },
+  "nav.main": {
+    groups: [{ id: "finance", label: "Finance", rank: 5 }],
+    entries: {
+      "nav:/products": { label: "Catalog", icon: Tag, order: -1 },
+      "nav:/payouts": { section: "finance" },
+      "nav:/price-lists": { parent: null },
+      "nav:/settings/commissions": { hidden: true },
+    },
+  },
+})
+```
+
+## Override a page
+
+A `page.tsx` at a path an earlier layer already serves replaces it. The component receives `renderDefault`,
+which renders the page it replaced:
+
+```tsx
+export default function ProductDetail({ renderDefault }) {
+  return (
+    <>
+      <ApprovalBanner />
+      {renderDefault?.()}
+    </>
+  )
+}
+```
+
+## Block the panel behind a flow
+
+There is no app-wrapper seam, as in Medusa. A flow every member must complete before using the panel
+(terms acceptance, a verification step) is a page plus a redirect: a `routes/<flow>/page.tsx` with
+`config.public = true` so it renders in the bare public layout, and a widget on the `topbar` zone that
+checks the status with `useQuery` and `navigate`s to the page while the flow is outstanding. The API keeps
+enforcing the rule with a 403 for everything else.
+
+## Register a layout
+
+A file under `layouts/` registers a layout other pages can pick. Augment `LayoutSectionRegistry` so the
+`sections` prop is typed.
+
+```tsx
+import { defineLayoutConfig } from "@mercurjs/dashboard-sdk"
+
+export default defineLayoutConfig({
+  id: "erp:three-column",
+  sections: [{ id: "main" }, { id: "left" }, { id: "right" }],
+  Component: ({ sections }) => (
+    <div className="grid grid-cols-3 gap-3">
+      {sections.left}
+      {sections.main}
+      {sections.right}
+    </div>
+  ),
+})
+```
+
+```ts
+declare module "@mercurjs/dashboard-sdk" {
+  interface LayoutSectionRegistry {
+    "erp:three-column": "main" | "left" | "right"
+  }
+}
+```