@mercurjs/docs 2.2.0-canary.40

package/content/references/workflows/product-edit/reject-product-change.mdx

@@ -0,0 +1,54 @@
+---
+title: "rejectProductChangeWorkflow"
+description: "Decline a pending ProductChange with an optional reason for the vendor."
+---
+
+Declines a pending `ProductChange`: validates the change exists and is still `pending`, then sets it to `declined` with `declined_by`, `declined_at`, and `declined_reason` — the staged actions are never applied to the master product. Emits `product-change.declined` with `{ id }`.
+
+## Usage
+
+```ts
+import { rejectProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+await rejectProductChangeWorkflow(container).run({
+  input: {
+    id: "prch_01H...",
+    declined_by: "user_01H...",
+    declined_reason: "Price change exceeds allowed range",
+  },
+})
+```
+
+## Input
+
+<ParamField body="id" type="string" required>
+  Id of the product change to decline. Must exist and be in `pending` status.
+</ParamField>
+
+<ParamField body="declined_by" type="string">
+  Actor id recorded as the decliner on the change.
+</ParamField>
+
+<ParamField body="declined_reason" type="string">
+  Vendor-facing reason stored on the change.
+</ParamField>
+
+<ParamField body="additional_data" type="object">
+  Arbitrary data forwarded to the `productChangeRejected` hook.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; the change status is updated in place.
+</ResponseField>
+
+## Hooks
+
+<ResponseField name="validate" type="hook">
+  Runs first with `{ input }` — use it to block rejection.
+</ResponseField>
+
+<ResponseField name="productChangeRejected" type="hook">
+  Runs after the decline with `{ id, additional_data }`.
+</ResponseField>

package/content/references/workflows/product-edit/stage-product-change.mdx

@@ -0,0 +1,75 @@
+---
+title: "stageProductChangeWorkflow"
+description: "Stage a pending ProductChange with its actions and optionally auto-confirm it."
+---
+
+Creates a `pending` `ProductChange` for one product, attaches the given actions to it, then runs `autoConfirmProductChangeWorkflow` — so the change is applied immediately when `auto_confirm` is `true` or the `product_request` feature flag is disabled. This is the engine behind the vendor product-edit workflows (`productEditUpdateProduct`, `productEditUpdateVariants`, `productEditUpdateAttributes`, `productEditDeleteProduct`). Emits `product-change.created`.
+
+## Usage
+
+```ts
+import { stageProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await stageProductChangeWorkflow(container).run({
+  input: {
+    product_id: "prod_01H...",
+    created_by: "sel_01H...",
+    actions: [
+      {
+        product_id: "prod_01H...",
+        action: "UPDATE",
+        details: { title: "Linen Shirt v2" },
+      },
+    ],
+  },
+})
+```
+
+## Input
+
+<ParamField body="product_id" type="string" required>
+  Id of the product the change targets.
+</ParamField>
+
+<ParamField body="actions" type="object[]" required>
+  Actions to stage on the change (`CreateProductChangeActionDTO` without `product_change_id`, which is stamped automatically).
+  <Expandable title="properties">
+    <ParamField body="product_id" type="string" required>
+      Id of the product the action applies to.
+    </ParamField>
+    <ParamField body="action" type="string" required>
+      Action type, e.g. `UPDATE`, `VARIANT_ADD`, `VARIANT_UPDATE`, `VARIANT_REMOVE`, `ATTRIBUTE_ADD`, `ATTRIBUTE_UPDATE`, `ATTRIBUTE_REMOVE`, `PRODUCT_DELETE`, `STATUS_CHANGE`.
+    </ParamField>
+    <ParamField body="details" type="object">
+      Operation payload applied when the change is confirmed.
+    </ParamField>
+    <ParamField body="internal_note" type="string">
+      Operator-only note on the action.
+    </ParamField>
+    <ParamField body="applied" type="boolean">
+      Whether the action is already applied; leave unset for staged edits.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="created_by" type="string">
+  Actor id who staged the change; also used as `confirmed_by` on auto-confirm.
+</ParamField>
+
+<ParamField body="internal_note" type="string">
+  Operator-only note stored on the change.
+</ParamField>
+
+<ParamField body="external_note" type="string">
+  Vendor-facing note stored on the change.
+</ParamField>
+
+<ParamField body="auto_confirm" type="boolean">
+  Force immediate confirmation even when the `product_request` feature flag is enabled.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="ProductChangeDTO">
+  The created change record; still `pending` unless it was auto-confirmed.
+</ResponseField>

package/content/references/workflows/seller/approve-seller.mdx

@@ -0,0 +1,34 @@
+---
+title: "approveSellerWorkflow"
+description: "Approve a pending seller and open its store."
+---
+
+Validates the seller can be approved, sets `status` to `open`, clears `status_reason`, and stamps `approved_at` on first approval. Triggered by `POST /admin/sellers/:id/approve`. Emits `seller.approved`.
+
+## Usage
+
+```ts
+import { approveSellerWorkflow } from "@mercurjs/core/workflows"
+
+await approveSellerWorkflow(container).run({
+  input: { seller_id: "sel_123" },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the seller to approve.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>
+
+## Hooks
+
+- `sellerApproved` — runs after approval with `{ seller_id }`.
+
+```ts
+approveSellerWorkflow.hooks.sellerApproved(async ({ seller_id }) => {
+  // e.g. send a welcome email
+})
+```

package/content/references/workflows/seller/create-seller-account.mdx

@@ -0,0 +1,59 @@
+---
+title: "createSellerAccountWorkflow"
+description: "Create a seller with its owner member during self-registration."
+---
+
+Creates a seller with `pending_approval` status, ensures the default seller roles exist, creates (or reuses) the owner member, and links the member's auth identity via app metadata. Optionally sets the seller address, professional details, and payment details in the same run. Triggered by `POST /vendor/sellers` during vendor registration. Emits `seller.created`.
+
+## Usage
+
+```ts
+import { createSellerAccountWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createSellerAccountWorkflow(container).run({
+  input: {
+    auth_identity_id: "authid_123",
+    seller: { name: "Acme", email: "hello@acme.co", currency_code: "usd" },
+    member_email: "owner@acme.co",
+    first_name: "Jane",
+    last_name: "Doe",
+  },
+})
+```
+
+## Input
+
+<ParamField body="auth_identity_id" type="string" required>Auth identity to bind to the owner member.</ParamField>
+<ParamField body="seller" type="CreateSellerDTO" required>
+  Seller to create; `status` is forced to `pending_approval`.
+  <Expandable title="properties">
+    <ParamField body="name" type="string" required>Display name of the seller.</ParamField>
+    <ParamField body="email" type="string" required>Contact email of the seller.</ParamField>
+    <ParamField body="currency_code" type="string" required>Default currency of the seller.</ParamField>
+    <ParamField body="handle" type="string">URL handle; auto-generated when omitted.</ParamField>
+    <ParamField body="description" type="string">Public seller description.</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="member_email" type="string">Email for the new owner member; required when `member_id` is not provided.</ParamField>
+<ParamField body="member_id" type="string">Existing member to link as owner instead of creating one.</ParamField>
+<ParamField body="first_name" type="string">Owner member first name.</ParamField>
+<ParamField body="last_name" type="string">Owner member last name.</ParamField>
+<ParamField body="address" type="UpdateSellerAddressDTO">Seller address to set after creation.</ParamField>
+<ParamField body="professional_details" type="UpdateProfessionalDetailsDTO">Professional details to set after creation.</ParamField>
+<ParamField body="payment_details" type="UpdatePaymentDetailsDTO">Payment details to set after creation.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="SellerDTO">The created seller.</ResponseField>
+
+## Hooks
+
+- `sellerAccountCreated` — runs after the account is assembled with `{ seller, additional_data }`.
+
+```ts
+createSellerAccountWorkflow.hooks.sellerAccountCreated(async ({ seller }) => {
+  // provision extra resources for the new seller
+})
+```

package/content/references/workflows/seller/create-seller-defaults.mdx

@@ -0,0 +1,22 @@
+---
+title: "createSellerDefaultsWorkflow"
+description: "Ensure the default seller roles exist."
+---
+
+Idempotently creates the built-in seller roles (administration, inventory management, order management, accounting, support). Run before assigning roles to members; also executed automatically by `createSellerAccountWorkflow` and `acceptMemberInviteWorkflow`.
+
+## Usage
+
+```ts
+import { createSellerDefaultsWorkflow } from "@mercurjs/core/workflows"
+
+await createSellerDefaultsWorkflow(container).run({})
+```
+
+## Input
+
+No input.
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/seller/create-sellers.mdx

@@ -0,0 +1,65 @@
+---
+title: "createSellersWorkflow"
+description: "Create one or more sellers and invite their first member."
+---
+
+Creates sellers (defaulting `status` to `pending_approval`), then runs `createMemberInvitesWorkflow` to invite each seller's initial member with the seller administration role. Triggered by `POST /admin/sellers`. Emits `seller.created` and `member_invite.created`.
+
+## Usage
+
+```ts
+import { createSellersWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createSellersWorkflow(container).run({
+  input: {
+    sellers: [
+      {
+        name: "Acme",
+        email: "hello@acme.co",
+        currency_code: "usd",
+        member: { email: "owner@acme.co" },
+      },
+    ],
+  },
+})
+```
+
+## Input
+
+<ParamField body="sellers" type="object[]" required>
+  Sellers to create.
+  <Expandable title="properties">
+    <ParamField body="name" type="string" required>Display name of the seller.</ParamField>
+    <ParamField body="email" type="string" required>Contact email of the seller.</ParamField>
+    <ParamField body="currency_code" type="string" required>Default currency of the seller.</ParamField>
+    <ParamField body="member" type="object" required>Initial member to invite; `{ email: string }`.</ParamField>
+    <ParamField body="handle" type="string">URL handle; auto-generated from the name when omitted.</ParamField>
+    <ParamField body="description" type="string">Public seller description.</ParamField>
+    <ParamField body="logo" type="string">Logo URL.</ParamField>
+    <ParamField body="banner" type="string">Banner URL.</ParamField>
+    <ParamField body="website_url" type="string">Seller website URL.</ParamField>
+    <ParamField body="external_id" type="string">External system identifier.</ParamField>
+    <ParamField body="status" type="string">One of `open`, `pending_approval`, `suspended`, `terminated`; defaults to `pending_approval`.</ParamField>
+    <ParamField body="status_reason" type="string">Reason attached to the current status.</ParamField>
+    <ParamField body="is_premium" type="boolean">Marks the seller as premium.</ParamField>
+    <ParamField body="closed_from" type="Date">Start of a store closure window.</ParamField>
+    <ParamField body="closed_to" type="Date">End of a store closure window.</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="SellerDTO[]">The created sellers.</ResponseField>
+
+## Hooks
+
+- `validate` — runs before creation with `{ input }`.
+- `sellersCreated` — runs after creation with `{ sellers, additional_data }`.
+
+```ts
+createSellersWorkflow.hooks.sellersCreated(async ({ sellers, additional_data }) => {
+  // react to new sellers
+})
+```

package/content/references/workflows/seller/delete-seller-professional-details.mdx

@@ -0,0 +1,37 @@
+---
+title: "deleteSellerProfessionalDetailsWorkflow"
+description: "Remove a seller's professional details."
+---
+
+Deletes the professional details record attached to a seller.
+
+## Usage
+
+```ts
+import { deleteSellerProfessionalDetailsWorkflow } from "@mercurjs/core/workflows"
+
+await deleteSellerProfessionalDetailsWorkflow(container).run({
+  input: { seller_id: "sel_123" },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the seller whose professional details are removed.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>
+
+## Hooks
+
+- `professionalDetailsDeleted` — runs after deletion with `{ seller_id, additional_data }`.
+
+```ts
+deleteSellerProfessionalDetailsWorkflow.hooks.professionalDetailsDeleted(
+  async ({ seller_id }) => {
+    // e.g. flag the seller for re-verification
+  }
+)
+```

package/content/references/workflows/seller/delete-sellers.mdx

@@ -0,0 +1,24 @@
+---
+title: "deleteSellersWorkflow"
+description: "Delete sellers by id."
+---
+
+Soft-deletes the given sellers. Emits `seller.deleted` for each id.
+
+## Usage
+
+```ts
+import { deleteSellersWorkflow } from "@mercurjs/core/workflows"
+
+await deleteSellersWorkflow(container).run({
+  input: { ids: ["sel_123"] },
+})
+```
+
+## Input
+
+<ParamField body="ids" type="string[]" required>Ids of the sellers to delete.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>

package/content/references/workflows/seller/invite-seller.mdx

@@ -0,0 +1,28 @@
+---
+title: "inviteSellerWorkflow"
+description: "Send a marketplace invitation email to a prospective seller."
+---
+
+Sends an invitation email (via the notification module, `email` channel) inviting someone to register as a seller, optionally with a registration link. Not wired to a core API route — run it from your own routes or automations. Does not create any seller records.
+
+## Usage
+
+```ts
+import { inviteSellerWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await inviteSellerWorkflow(container).run({
+  input: {
+    email: "owner@acme.co",
+    registration_url: "https://vendor.example.com/register",
+  },
+})
+```
+
+## Input
+
+<ParamField body="email" type="string" required>Recipient of the invitation email.</ParamField>
+<ParamField body="registration_url" type="string">Link rendered as the email's call-to-action button.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="NotificationDTO">The created email notification.</ResponseField>

package/content/references/workflows/seller/suspend-seller.mdx

@@ -0,0 +1,35 @@
+---
+title: "suspendSellerWorkflow"
+description: "Suspend a seller with an optional reason."
+---
+
+Validates the seller can be suspended, sets `status` to `suspended`, records the reason, and stamps `rejected_at` on first suspension. Triggered by `POST /admin/sellers/:id/suspend`. Emits `seller.suspended`.
+
+## Usage
+
+```ts
+import { suspendSellerWorkflow } from "@mercurjs/core/workflows"
+
+await suspendSellerWorkflow(container).run({
+  input: { seller_id: "sel_123", reason: "Policy violation" },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the seller to suspend.</ParamField>
+<ParamField body="reason" type="string">Reason stored in `status_reason`.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>
+
+## Hooks
+
+- `sellerSuspended` — runs after suspension with `{ seller_id }`.
+
+```ts
+suspendSellerWorkflow.hooks.sellerSuspended(async ({ seller_id }) => {
+  // e.g. pause the seller's listings
+})
+```

package/content/references/workflows/seller/terminate-seller.mdx

@@ -0,0 +1,35 @@
+---
+title: "terminateSellerWorkflow"
+description: "Terminate a seller with an optional reason."
+---
+
+Validates the seller can be terminated, then sets `status` to `terminated` and records the reason. Emits `seller.terminated`.
+
+## Usage
+
+```ts
+import { terminateSellerWorkflow } from "@mercurjs/core/workflows"
+
+await terminateSellerWorkflow(container).run({
+  input: { seller_id: "sel_123", reason: "Account closure requested" },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the seller to terminate.</ParamField>
+<ParamField body="reason" type="string">Reason stored in `status_reason`.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>
+
+## Hooks
+
+- `sellerTerminated` — runs after termination with `{ seller_id }`.
+
+```ts
+terminateSellerWorkflow.hooks.sellerTerminated(async ({ seller_id }) => {
+  // e.g. archive the seller's data
+})
+```

package/content/references/workflows/seller/unsuspend-seller.mdx

@@ -0,0 +1,34 @@
+---
+title: "unsuspendSellerWorkflow"
+description: "Lift a seller suspension."
+---
+
+Validates the seller is currently suspended, then sets `status` back to `open` and clears `status_reason`. Triggered by `POST /admin/sellers/:id/unsuspend`. Emits `seller.unsuspended`.
+
+## Usage
+
+```ts
+import { unsuspendSellerWorkflow } from "@mercurjs/core/workflows"
+
+await unsuspendSellerWorkflow(container).run({
+  input: { seller_id: "sel_123" },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the suspended seller.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>
+
+## Hooks
+
+- `sellerUnsuspended` — runs after the status change with `{ seller_id }`.
+
+```ts
+unsuspendSellerWorkflow.hooks.sellerUnsuspended(async ({ seller_id }) => {
+  // e.g. re-enable listings
+})
+```

package/content/references/workflows/seller/unterminate-seller.mdx

@@ -0,0 +1,34 @@
+---
+title: "unterminateSellerWorkflow"
+description: "Revert a terminated seller back to suspended."
+---
+
+Validates the seller is currently terminated, then sets `status` to `suspended` and clears `status_reason`. The seller must be unsuspended separately to reopen the store. Emits `seller.unterminated`.
+
+## Usage
+
+```ts
+import { unterminateSellerWorkflow } from "@mercurjs/core/workflows"
+
+await unterminateSellerWorkflow(container).run({
+  input: { seller_id: "sel_123" },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the terminated seller.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">Nothing is returned.</ResponseField>
+
+## Hooks
+
+- `sellerUnterminated` — runs after the status change with `{ seller_id }`.
+
+```ts
+unterminateSellerWorkflow.hooks.sellerUnterminated(async ({ seller_id }) => {
+  // e.g. notify the operator
+})
+```

package/content/references/workflows/seller/update-seller-address.mdx

@@ -0,0 +1,55 @@
+---
+title: "updateSellerAddressWorkflow"
+description: "Upsert a seller's address."
+---
+
+Creates or updates the address record attached to a seller. Also run as a step by `createSellerAccountWorkflow` when an address is provided at registration.
+
+## Usage
+
+```ts
+import { updateSellerAddressWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await updateSellerAddressWorkflow(container).run({
+  input: {
+    seller_id: "sel_123",
+    data: { address_1: "1 Main St", city: "Berlin", country_code: "de" },
+  },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the seller whose address is updated.</ParamField>
+<ParamField body="data" type="UpdateSellerAddressDTO" required>
+  Address fields to set; all optional.
+  <Expandable title="properties">
+    <ParamField body="name" type="string">Address label.</ParamField>
+    <ParamField body="company" type="string">Company name.</ParamField>
+    <ParamField body="first_name" type="string">Contact first name.</ParamField>
+    <ParamField body="last_name" type="string">Contact last name.</ParamField>
+    <ParamField body="address_1" type="string">Street address, line 1.</ParamField>
+    <ParamField body="address_2" type="string">Street address, line 2.</ParamField>
+    <ParamField body="city" type="string">City.</ParamField>
+    <ParamField body="country_code" type="string">ISO 2-letter country code.</ParamField>
+    <ParamField body="province" type="string">Province or state.</ParamField>
+    <ParamField body="postal_code" type="string">Postal code.</ParamField>
+    <ParamField body="phone" type="string">Phone number.</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="SellerAddressDTO">The updated address.</ResponseField>
+
+## Hooks
+
+- `addressUpdated` — runs after the update with `{ address, additional_data }`.
+
+```ts
+updateSellerAddressWorkflow.hooks.addressUpdated(async ({ address }) => {
+  // e.g. re-verify tax settings
+})
+```

package/content/references/workflows/seller/update-seller-payment-details.mdx

@@ -0,0 +1,52 @@
+---
+title: "updateSellerPaymentDetailsWorkflow"
+description: "Upsert a seller's bank payment details."
+---
+
+Creates or updates the payment details record attached to a seller. Also run as a step by `createSellerAccountWorkflow` when payment details are provided at registration.
+
+## Usage
+
+```ts
+import { updateSellerPaymentDetailsWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await updateSellerPaymentDetailsWorkflow(container).run({
+  input: {
+    seller_id: "sel_123",
+    data: { holder_name: "Acme GmbH", iban: "DE89370400440532013000" },
+  },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>Id of the seller whose payment details are updated.</ParamField>
+<ParamField body="data" type="UpdatePaymentDetailsDTO" required>
+  Payment fields to set; all optional.
+  <Expandable title="properties">
+    <ParamField body="country_code" type="string">Bank country code.</ParamField>
+    <ParamField body="holder_name" type="string">Account holder name.</ParamField>
+    <ParamField body="bank_name" type="string">Bank name.</ParamField>
+    <ParamField body="iban" type="string">IBAN.</ParamField>
+    <ParamField body="bic" type="string">BIC / SWIFT code.</ParamField>
+    <ParamField body="routing_number" type="string">Routing number.</ParamField>
+    <ParamField body="account_number" type="string">Account number.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="PaymentDetailsDTO">The updated payment details.</ResponseField>
+
+## Hooks
+
+- `paymentDetailsUpdated` — runs after the update with `{ payment_details, additional_data }`.
+
+```ts
+updateSellerPaymentDetailsWorkflow.hooks.paymentDetailsUpdated(
+  async ({ payment_details }) => {
+    // e.g. trigger payout account re-verification
+  }
+)
+```