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

package/content/platform/store/guides/manage-the-team.mdx

@@ -1,55 +1,145 @@
 ---
-title: "Manage the team"
+title: "Manage a store's team from server code"
 sidebarTitle: "Manage the team"
-description: "Invite and add store members from server code."
+description: "Invite members, accept invites, add existing members, change roles, and remove members with the Seller module workflows."
 ---
 
-In this guide, you'll learn how to manage a store's team from your own server
-code. You can invite members, add them directly, and update their roles.
+Manage a store’s team from your own server code when you migrate staff from another system, sync people from an identity provider, or build your own team screens. Every change runs through a workflow that validates the owner rules and emits an event.
 
-## Invite a member
+## Before you begin
 
-`inviteSellerWorkflow` creates a `MemberInvite` and sends the invitation email.
-The invitee sets up access and is linked to the store when they accept.
+You need the following in place:
 
-```ts title="src/api/custom/invite/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { inviteSellerWorkflow } from "@mercurjs/core/workflows"
+- A store id, such as `sel_01JD8Q1234567`
+- A notification provider for email, if you send invite links from a subscriber
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  await inviteSellerWorkflow(req.scope).run({
-    input: {
-      email: "ops@acme.com",
-      seller_id: req.params.id,
-    },
-  })
+## Invite and onboard a member
 
-  res.sendStatus(200)
-}
-```
+<Steps>
+  <Step title="Create the invite">
+    `createMemberInvitesWorkflow` takes an array of invites, each with `seller_id`, `email`, and `role_id`. It signs a token for each one and fails if an email already belongs to the store.
+
+    ```ts
+    import { SellerRole } from "@mercurjs/types"
+    import { createMemberInvitesWorkflow } from "@mercurjs/core/workflows"
+
+    const { result: invites } = await createMemberInvitesWorkflow(
+      container
+    ).run({
+      input: [
+        {
+          seller_id: "sel_01JD8Q1234567",
+          email: "ops@acme.com",
+          role_id: SellerRole.ORDER_MANAGEMENT,
+        },
+      ],
+    })
+    ```
+  </Step>
+  <Step title="Send the invite link">
+    The workflow emits `member_invite.created` once per invite, with `id`, `token`, and `expires_at`. Mercur doesn’t email team invites itself, so send the link from a subscriber.
+
+    ```ts title="src/subscribers/member-invite-created.ts"
+    import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+    import { Modules } from "@medusajs/framework/utils"
+    import { MercurModules } from "@mercurjs/types"
+
+    export default async function inviteCreated({
+      event,
+      container,
+    }: SubscriberArgs<{ id: string; token: string }>) {
+      const sellers = container.resolve(MercurModules.SELLER)
+      const invite = await sellers.retrieveMemberInvite(event.data.id)
+      await container.resolve(Modules.NOTIFICATION).createNotifications({
+        to: invite.email,
+        channel: "email",
+        template: "member-invite",
+        data: { token: event.data.token },
+      })
+    }
+
+    export const config: SubscriberConfig = { event: "member_invite.created" }
+    ```
+  </Step>
+  <Step title="Accept the invite">
+    When the invitee signs up or signs in, run `acceptMemberInviteWorkflow` with the token and their auth identity. It returns the member.
+
+    ```ts
+    import { acceptMemberInviteWorkflow } from "@mercurjs/core/workflows"
 
-## Add a member directly
+    const { result: member } = await acceptMemberInviteWorkflow(
+      req.scope
+    ).run({
+      input: {
+        invite_token: "your_invite_token",
+        auth_identity_id: req.auth_context.auth_identity_id,
+        first_name: "Ola",
+        last_name: "Nordmann",
+      },
+    })
+    ```
 
-When you already have the user, for example during a migration, add them to a
-store without the invite step. Use `addSellerMemberWorkflow`.
+    The workflow upserts the member by email, creates the membership with the invite’s role, and deletes the invite. Pass `member_id` when the person is already a member of another store, so the workflow leaves their auth identity as it is.
+  </Step>
+</Steps>
+
+## Resend or revoke an invite
+
+`resendMemberInviteWorkflow` takes `invite_id` and `seller_id`. It deletes the invite and creates a fresh one with a new token and expiry, then emits `member_invite.created` again. `deleteMemberInviteWorkflow` takes `invite_id` and deletes the invite without a replacement.
+
+## Add an existing member directly
+
+Skip the invite when the person already has a `Member` record, for example after a migration. `addSellerMemberWorkflow` creates the membership and returns it.
 
 ```ts
+import { SellerRole } from "@mercurjs/types"
 import { addSellerMemberWorkflow } from "@mercurjs/core/workflows"
 
 await addSellerMemberWorkflow(container).run({
   input: {
-    seller_id: "sel_123",
-    member: { email: "ops@acme.com" },
+    seller_id: "sel_01JD8Q1234567",
+    member_id: "mem_01JD8Q1234567",
+    role_id: SellerRole.SUPPORT,
   },
 })
 ```
 
-<Tip>
-  Every store must keep at least one admin member. A workflow that would remove or
-  demote the last admin fails instead of leaving a store unadministered.
-</Tip>
+The membership is unique on `(seller_id, member_id)`, so adding the same member twice fails.
+
+## Change a role or remove a member
+
+Both workflows take the membership id, `seller_member_id`, not the member id. Both reject the owner membership with a `NOT_ALLOWED` error.
+
+```ts
+import { SellerRole } from "@mercurjs/types"
+import {
+  removeSellerMemberWorkflow,
+  updateMemberRoleWorkflow,
+} from "@mercurjs/core/workflows"
+
+await updateMemberRoleWorkflow(container).run({
+  input: {
+    seller_member_id: "selmem_01JD8Q1234567",
+    role_id: SellerRole.ACCOUNTING,
+  },
+})
+
+await removeSellerMemberWorkflow(container).run({
+  input: {
+    seller_member_id: "selmem_01JD8Q1234567",
+    seller_id: "sel_01JD8Q1234567",
+  },
+})
+```
+
+Removing a membership keeps the `Member` record, so the person keeps access to their other stores.
+
+## Update a member’s profile
+
+`updateMemberWorkflow` changes `first_name`, `last_name`, and `locale` on members that match a `selector`. It exposes a `membersUpdated` hook and doesn’t emit an event.
 
-## Accept an invite
+## Next steps
 
-The invitee's acceptance runs through `acceptMemberInviteWorkflow`. It links the
-member to the store, and if the email already exists, it reuses their account.
+- [How store teams work](/platform/store/concepts/team)
+- [Event reference](/platform/store/reference/events)
+- [Workflows reference](/platform/store/reference/workflows)

package/content/platform/store/guides/moderate-a-store.mdx

@@ -1,59 +1,128 @@
 ---
-title: "Moderate stores"
+title: "Approve, suspend, and terminate stores"
 sidebarTitle: "Moderate stores"
-description: "Approve, suspend, and terminate stores from server code."
+description: "Move stores through their lifecycle from server code, extend each transition with a hook, and react to the events."
 ---
 
-In this guide, you'll learn how to drive a store through its lifecycle from your
-own server code. Each transition has a dedicated workflow, so the side effects
-(events, notifications, and compensation) run consistently.
+Drive a store through its lifecycle from your own server code, for example to auto-approve vetted sellers or to suspend a store when a risk check fails. Each transition is a workflow that validates the current status, writes the change, emits an event, and exposes a hook.
 
-## Approve a store
+## Moderate a store
 
-Move a `pending_approval` store to `open` with `approveSellerWorkflow`.
+<Steps>
+  <Step title="Approve a pending store">
+    `approveSellerWorkflow` moves a `pending_approval` store to `open` and stamps `approved_at`.
 
-```ts title="src/api/custom/approve/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { approveSellerWorkflow } from "@mercurjs/core/workflows"
+    ```ts title="src/api/admin/stores/[id]/vet/route.ts"
+    import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    import { approveSellerWorkflow } from "@mercurjs/core/workflows"
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  await approveSellerWorkflow(req.scope).run({
-    input: { seller_id: req.params.id },
-  })
+    export async function POST(req: MedusaRequest, res: MedusaResponse) {
+      await approveSellerWorkflow(req.scope).run({
+        input: { seller_id: req.params.id },
+      })
 
-  res.sendStatus(200)
-}
-```
+      res.sendStatus(200)
+    }
+    ```
+  </Step>
+  <Step title="Suspend and reinstate a store">
+    `suspendSellerWorkflow` takes an optional `reason`, which it saves in `status_reason`. `unsuspendSellerWorkflow` reopens the store and clears the reason.
 
-## Suspend and reinstate
+    ```ts
+    import {
+      suspendSellerWorkflow,
+      unsuspendSellerWorkflow,
+    } from "@mercurjs/core/workflows"
 
-Freeze an `open` store's operations, then reinstate it once the issue is resolved.
+    await suspendSellerWorkflow(container).run({
+      input: { seller_id: "sel_01JD8Q1234567", reason: "Chargeback review" },
+    })
 
-```ts
-import {
-  suspendSellerWorkflow,
-  unsuspendSellerWorkflow,
-} from "@mercurjs/core/workflows"
-
-await suspendSellerWorkflow(container).run({ input: { seller_id } })
-// ...later
-await unsuspendSellerWorkflow(container).run({ input: { seller_id } })
-```
+    await unsuspendSellerWorkflow(container).run({
+      input: { seller_id: "sel_01JD8Q1234567" },
+    })
+    ```
+  </Step>
+  <Step title="Terminate a store">
+    `terminateSellerWorkflow` accepts a `pending_approval` or `suspended` store. Suspend an `open` store first.
+
+    ```ts
+    import { terminateSellerWorkflow } from "@mercurjs/core/workflows"
+
+    await terminateSellerWorkflow(container).run({
+      input: { seller_id: "sel_01JD8Q1234567", reason: "Policy breach" },
+    })
+    ```
 
-## Terminate a store
+    To undo it, run `unterminateSellerWorkflow`. It returns the store to `suspended`, and you reopen it with `unsuspendSellerWorkflow`.
+  </Step>
+</Steps>
+
+## Reject a pending application
+
+Mercur has no separate reject workflow. Run `suspendSellerWorkflow` on the `pending_approval` store with a `reason`: it stamps `rejected_at` and keeps the store out of the Store API. Terminate it afterwards if the decision is final.
+
+## Handle a failed transition
+
+Each workflow checks the starting status and fails with a `NOT_ALLOWED` error when the transition isn’t allowed. Nothing is written in that case. Pass `throwOnError: false` to read the error instead of catching it.
 
 ```ts
+import { MedusaError } from "@medusajs/framework/utils"
 import { terminateSellerWorkflow } from "@mercurjs/core/workflows"
 
-await terminateSellerWorkflow(container).run({ input: { seller_id } })
+const { errors } = await terminateSellerWorkflow(container).run({
+  input: { seller_id: "sel_01JD8Q1234567" },
+  throwOnError: false,
+})
+
+const notAllowed = errors.some(
+  ({ error }) => error.type === MedusaError.Types.NOT_ALLOWED
+)
+```
+
+An `open` store makes `notAllowed` true here, with the message “Cannot terminate an open seller. Suspend or close first.”
+
+The workflow also fails when the seller id doesn’t exist, because its lookup step runs with `throwIfKeyNotFound`.
+
+## Extend a transition with a hook
+
+Each lifecycle workflow exposes a hook that receives `seller_id` and `additional_data`. Register a handler to run your own step inside the transition.
+
+```ts title="src/workflows/hooks/seller-approved.ts"
+import { approveSellerWorkflow } from "@mercurjs/core/workflows"
+
+approveSellerWorkflow.hooks.sellerApproved(
+  async ({ seller_id }, { container }) => {
+    const logger = container.resolve("logger")
+    logger.info(`Store ${seller_id} approved`)
+  }
+)
 ```
 
-<Warning>
-  Termination is irreversible. All orders and payouts must be resolved first.
-</Warning>
+The other hooks follow the same shape: `sellerSuspended`, `sellerUnsuspended`, `sellerTerminated`, and `sellerUnterminated`.
+
+## Run side effects from a subscriber
+
+Subscribe to the lifecycle events for work that shouldn’t block the transition, such as emails. Each event carries `{ id }`, the seller id.
+
+```ts title="src/subscribers/store-suspended.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function storeSuspended({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const logger = container.resolve("logger")
+  logger.info(`Store ${event.data.id} suspended`)
+}
+
+export const config: SubscriberConfig = {
+  event: "seller.suspended",
+}
+```
 
-## React to lifecycle changes
+## Next steps
 
-To run your own side effects when a store's status changes, subscribe to the
-events these workflows emit instead of polling. The
-[Event reference](/platform/store/reference/events) lists the event names.
+- [Store statuses and transitions](/platform/store/concepts/lifecycle)
+- [Event reference](/platform/store/reference/events)
+- [Workflows reference](/platform/store/reference/workflows)

package/content/platform/store/overview.mdx

@@ -1,46 +1,53 @@
 ---
-title: "Store"
+title: "Stores"
 sidebarTitle: "Overview"
-description: "Manage sellers, their teams, and their lifecycle on the marketplace."
+description: "Control who sells on your marketplace, who works on each store, and when a store can trade."
 ---
 
-Use Mercur to control who is allowed to sell on your marketplace and what each
-person on a store's team can do.
+Use Mercur to decide who can sell on your marketplace and what each person on a store’s team can do.
 
-Governing your sellers starts here. The Store domain decides who may sell,
-enforces role-based access so every member acts only within their store, and
-keeps each store's data isolated from the rest. On top of that control layer, a
-store carries its own team, a governed account lifecycle, and the business
-details used to settle payouts. Every offer, order, payout, and storefront page
-belongs to a store, and all of it is exposed directly through the Admin and
-Vendor APIs.
+A store is the account a seller trades under. Offers, orders, payouts, and storefront pages all link back to it, and its team works only inside it. The Seller module holds the store record, its business details, its members and invites, and its status. Other marketplace modules attach to a store through module links, never through direct references.
+
+<img className="block dark:hidden" src="/images/figures/store-overview-light.svg" alt="A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles." />
+<img className="hidden dark:block" src="/images/figures/store-overview-dark.svg" alt="A Stores list from the Seller module showing four stores, each with its status, currency, member count, and premium flag, in front of the Team panel for acme-supplies with three members and their seller roles." />
 
 <Note>
-  A store is the `Seller` entity. The Admin and Vendor panels call it a "Store".
-  The API and core modules call the same record a `Seller` (id prefix `sel`). You
-  never need to know Medusa to work with stores.
+  The Admin and Vendor panels call it a store. The code calls the same record a `Seller` (id prefix `sel`), and you resolve its module with `MercurModules.SELLER` from `@mercurjs/types`.
 </Note>
 
 ## Key features
 
-- **Role-based access control:** many-to-many members, roles resolved per store, and a store switcher for users who belong to several stores.
-- **Store isolation:** each store sees and acts on only its own data.
-- **Governed lifecycle:** a four-state account model with operator-only transitions.
-- **Self-service onboarding:** create stores yourself, or let sellers register publicly.
-- **Scheduled closures:** temporary offline windows that don't change account status.
-- **Premium placement:** an operator-only flag the storefront uses for featured curation.
-- **Single-currency accounts:** each store settles in exactly one currency.
+The Seller module covers the full life of a store account:
+
+- **Many-to-many teams**: a member can belong to several stores and picks the active one per request
+- **Owner protection**: the store’s owner membership can’t be removed or have its role changed
+- **Seller roles**: each membership stores one of five `SellerRole` values, from administration to support
+- **Token-based invites**: signed invite tokens that expire after 7 days by default
+- **Governed lifecycle**: four statuses, each transition run by its own workflow with a hook and an event
+- **Scheduled closures**: a `closed_from` and `closed_to` window that hides a store from the Store API without changing its status
+- **Premium flag**: an `is_premium` boolean the operator sets for featured placement
+- **Region assignment**: every store links to one or more regions, starting with the default region
+
+## How it works
+
+A store moves from creation to trading in a fixed order:
+
+1. A seller registers, or your code runs `createSellersWorkflow`, and the store starts in `pending_approval`
+2. The workflow links the store to the default region and to any `region_ids` you pass
+3. The first member joins as owner, either at registration or by accepting the invite the workflow sends
+4. The operator runs `approveSellerWorkflow`, and the store becomes `open`
+5. The Store API lists the store and its offers while it’s `open` and outside a closure window
 
 ## Get started
 
-Learn how the domain fits together.
+Learn how stores, teams, and statuses fit together.
 
 <CardGroup cols={2}>
   <Card title="The store" icon="store" href="/platform/store/concepts/store-entity">
-    The seller entity, its profile, currency, and business identity.
+    The seller record, its currency, regions, and business details.
   </Card>
   <Card title="Team & members" icon="users" href="/platform/store/concepts/team">
-    Multi-user stores, roles, invites, and the store switcher.
+    Members, owners, roles, invites, and the active store.
   </Card>
   <Card title="Lifecycle" icon="arrows-rotate" href="/platform/store/concepts/lifecycle">
     Statuses, transitions, scheduled closures, and premium.
@@ -49,38 +56,38 @@ Learn how the domain fits together.
 
 ## Examples
 
-Build against the Store domain in your own code.
+Build against stores in your own server code.
 
 <CardGroup cols={2}>
   <Card title="Create a store" icon="plus" href="/platform/store/guides/create-a-store">
-    Run `createSellersWorkflow` from a route or seed script.
+    Run `createSellersWorkflow` from a route or a seed script.
   </Card>
   <Card title="Moderate stores" icon="gavel" href="/platform/store/guides/moderate-a-store">
-    Approve, suspend, and terminate stores in code.
+    Approve, suspend, terminate, and reinstate stores in code.
   </Card>
   <Card title="Manage the team" icon="user-plus" href="/platform/store/guides/manage-the-team">
-    Invite and add members programmatically.
+    Invite, add, re-role, and remove members.
   </Card>
 </CardGroup>
 
 ## Resources
 
-Data models, workflows, service methods, and events for the Store domain.
+The data models, links, workflows, service methods, and events behind stores.
 
 <CardGroup cols={2}>
   <Card title="Data models" icon="table" href="/platform/store/reference/data-models">
-    The `Seller`, `Member`, and related entities.
+    `Seller`, `Member`, `SellerMember`, `MemberInvite`, and the satellite records.
   </Card>
   <Card title="Links" icon="link" href="/platform/store/reference/links">
-    How the Store domain links to other modules.
+    How a store connects to orders, offers, payouts, regions, and more.
   </Card>
   <Card title="Workflows" icon="diagram-project" href="/platform/store/reference/workflows">
-    Seller and member lifecycle workflows.
+    Store, lifecycle, and team workflows with their hooks.
   </Card>
   <Card title="Service" icon="gear" href="/platform/store/reference/service">
-    Module service methods for working with records directly.
+    Seller module service methods for direct reads and writes.
   </Card>
   <Card title="Events" icon="bell" href="/platform/store/reference/events">
-    Events emitted as stores and members change.
+    Events emitted as stores, members, and invites change.
   </Card>
 </CardGroup>