@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/references/workflows/product-attribute/update-product-attributes-on-product.mdx

@@ -1,41 +0,0 @@
----
-title: "updateProductAttributesOnProductWorkflow"
-description: "Mutate a product's per-attribute value selections."
----
-
-Handles the `update` portion of the attribute batch engine (`createAndLinkProductAttributesToProductWorkflow`). For shared axis attributes it adjusts the per-product value subset of the mirror option and keeps the value-link pivot in sync; for exclusive (product-scoped) axis attributes it creates or deletes values on the exclusive option; for `text`/`unit` it swaps the linked value's name (or creates one); for `toggle` it re-links the matching `true`/`false` value. A `title` on a product-scoped attribute renames it via `updateProductAttributesWorkflow`.
-
-## Usage
-
-```ts
-import { updateProductAttributesOnProductWorkflow } from "@mercurjs/core/workflows"
-
-await updateProductAttributesOnProductWorkflow(container).run({
-  input: {
-    product_id: "prod_123",
-    update: [
-      { id: "pattr_size", add: ["pattrval_xl"], remove: ["pattrval_s"] },
-      { id: "pattr_material", value: "Linen" },
-    ],
-  },
-})
-```
-
-## Input
-
-<ParamField body="product_id" type="string" required>The product whose attribute selections are updated.</ParamField>
-<ParamField body="update" type="ProductAttributeBatchUpdate[]" required>
-  Per-attribute updates.
-  <Expandable title="properties">
-    <ParamField body="id" type="string" required>Id of the existing attribute to update.</ParamField>
-    <ParamField body="title" type="string">New name; only honoured for product-scoped attributes and propagated to the mirror option title.</ParamField>
-    <ParamField body="add" type="(string | { value: string })[]">Value ids to add (shared axis subset) or new value objects to create (exclusive axis).</ParamField>
-    <ParamField body="remove" type="string[]">Value ids to remove from the selection (exclusive-axis values are deleted).</ParamField>
-    <ParamField body="value" type="string | number | boolean">New scalar for `text` / `unit` / `toggle` attributes.</ParamField>
-  </Expandable>
-</ParamField>
-<ParamField body="additional_data" type="object">Custom data passed through.</ParamField>
-
-## Result
-
-<ResponseField name="result" type="void">No return value.</ResponseField>

package/content/references/workflows/product-attribute/update-product-attributes.mdx

@@ -1,48 +0,0 @@
----
-title: "updateProductAttributesWorkflow"
-description: "Update attributes matching a selector and sync mirror option titles."
----
-
-Updates product attributes by selector. When `name` changes, the mirror `ProductOption` title of any affected axis attribute is updated to match. Triggered by `POST /admin/product-attributes/:id`. Emits `product-attribute.updated`.
-
-## Usage
-
-```ts
-import { updateProductAttributesWorkflow } from "@mercurjs/core/workflows"
-
-const { result } = await updateProductAttributesWorkflow(container).run({
-  input: {
-    selector: { id: "pattr_123" },
-    update: { name: "Colour", is_filterable: true },
-  },
-})
-```
-
-## Input
-
-<ParamField body="selector" type="object" required>Filter for the attributes to update, e.g. `{ id: "pattr_123" }`.</ParamField>
-<ParamField body="update" type="UpdateProductAttributeDTO" required>
-  Fields to set on every matched attribute.
-  <Expandable title="properties">
-    <ParamField body="name" type="string">New display name; propagated to mirror option titles.</ParamField>
-    <ParamField body="handle" type="string">New handle.</ParamField>
-    <ParamField body="description" type="string | null">New description.</ParamField>
-    <ParamField body="type" type="AttributeType">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ParamField>
-    <ParamField body="is_required" type="boolean">Whether products must carry this attribute.</ParamField>
-    <ParamField body="is_filterable" type="boolean">Whether the attribute is a storefront filter.</ParamField>
-    <ParamField body="is_variant_axis" type="boolean">Whether the attribute is a variant axis.</ParamField>
-    <ParamField body="rank" type="number">Sort rank.</ParamField>
-    <ParamField body="is_active" type="boolean">Whether the attribute is active.</ParamField>
-    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
-  </Expandable>
-</ParamField>
-<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
-
-## Result
-
-<ResponseField name="result" type="ProductAttributeDTO[]">The updated attributes.</ResponseField>
-
-## Hooks
-
-- `validate` — runs before the update with `{ input }`.
-- `productAttributesUpdated` — runs after the update with `{ attributes, additional_data }`.

package/content/references/workflows/product-attribute/upsert-product-attribute-values.mdx

@@ -1,43 +0,0 @@
----
-title: "upsertProductAttributeValuesWorkflow"
-description: "Create or update attribute values in one call, keyed by id presence."
----
-
-Splits the given values by `id`: entries without an id are created on the attribute, entries with an id are updated in place. Unlike the create/update value workflows it does not touch the mirror `ProductOption` (renaming a value in place does not re-sync the mirrored option) and it emits no events.
-
-## Usage
-
-```ts
-import { upsertProductAttributeValuesWorkflow } from "@mercurjs/core/workflows"
-
-const { result } = await upsertProductAttributeValuesWorkflow(container).run({
-  input: {
-    attribute_id: "pattr_color",
-    values: [
-      { name: "Teal" },
-      { id: "pattrval_123", name: "Navy Blue" },
-    ],
-  },
-})
-```
-
-## Input
-
-<ParamField body="attribute_id" type="string" required>The attribute the values belong to.</ParamField>
-<ParamField body="values" type="UpsertProductAttributeValueDTO[]" required>
-  Values to create (no `id`) or update (with `id`).
-  <Expandable title="properties">
-    <ParamField body="id" type="string">Existing value id; omit to create a new value.</ParamField>
-    <ParamField body="name" type="string">Display name of the value.</ParamField>
-    <ParamField body="handle" type="string">URL-safe handle.</ParamField>
-    <ParamField body="rank" type="number">Sort rank.</ParamField>
-    <ParamField body="is_active" type="boolean">Whether the value is active.</ParamField>
-    <ParamField body="product_option_value_id" type="string | null">Bound mirror option value.</ParamField>
-    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
-  </Expandable>
-</ParamField>
-<ParamField body="additional_data" type="object">Custom data passed through.</ParamField>
-
-## Result
-
-<ResponseField name="result" type="ProductAttributeValueDTO[]">The created values followed by the updated values.</ResponseField>

package/content/references/workflows/product-edit/auto-confirm-product-change.mdx

@@ -1,39 +0,0 @@
----
-title: "autoConfirmProductChangeWorkflow"
-description: "Conditionally confirm a ProductChange based on the product_request feature flag."
----
-
-Decides whether a freshly staged `ProductChange` should be confirmed immediately: it runs `confirmProductChangeWorkflow` for the change when `force` is `true` or the `product_request` feature flag is disabled, and does nothing otherwise (leaving the change `pending` for operator review). Run as a step by `stageProductChangeWorkflow`. Any events (`product-change.confirmed`) come from the nested confirm workflow.
-
-## Usage
-
-```ts
-import { autoConfirmProductChangeWorkflow } from "@mercurjs/core/workflows"
-
-await autoConfirmProductChangeWorkflow(container).run({
-  input: {
-    change_id: "prch_01H...",
-    confirmed_by: "sel_01H...",
-  },
-})
-```
-
-## Input
-
-<ParamField body="change_id" type="string" required>
-  Id of the product change to (conditionally) confirm.
-</ParamField>
-
-<ParamField body="confirmed_by" type="string">
-  Actor id forwarded as `confirmed_by` to the confirm workflow.
-</ParamField>
-
-<ParamField body="force" type="boolean">
-  Confirm regardless of the `product_request` feature flag.
-</ParamField>
-
-## Result
-
-<ResponseField name="result" type="void">
-  Returns nothing; the change is either confirmed (and its actions applied) or left `pending`.
-</ResponseField>

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

@@ -1,49 +0,0 @@
----
-title: "cancelProductChangeWorkflow"
-description: "Cancel a pending ProductChange so its staged actions are never applied."
----
-
-Cancels a pending `ProductChange`: validates the change exists and is still `pending`, then sets it to `canceled` with `canceled_by` and `canceled_at` — the staged actions are never applied to the master product. Triggered by `POST /admin/product-changes/:id/cancel` (operator) and `POST /vendor/products/:id/cancel` (vendor withdrawing their own edit). Emits `product-change.canceled` with `{ id }`.
-
-## Usage
-
-```ts
-import { cancelProductChangeWorkflow } from "@mercurjs/core/workflows"
-
-await cancelProductChangeWorkflow(container).run({
-  input: {
-    id: "prch_01H...",
-    canceled_by: "sel_01H...",
-  },
-})
-```
-
-## Input
-
-<ParamField body="id" type="string" required>
-  Id of the product change to cancel. Must exist and be in `pending` status.
-</ParamField>
-
-<ParamField body="canceled_by" type="string">
-  Actor id recorded as the canceler on the change.
-</ParamField>
-
-<ParamField body="additional_data" type="object">
-  Arbitrary data forwarded to the `productChangeCanceled` 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 cancellation.
-</ResponseField>
-
-<ResponseField name="productChangeCanceled" type="hook">
-  Runs after cancellation with `{ id, additional_data }`.
-</ResponseField>

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

@@ -1,57 +0,0 @@
----
-title: "confirmProductChangeWorkflow"
-description: "Confirm pending ProductChanges and apply their staged actions to the master product."
----
-
-Confirms one or more pending `ProductChange` records: validates each change exists and is confirmable, marks them `confirmed` with `confirmed_by`, then runs the internal apply engine (`applyProductChangeActionsWorkflow`) to write the staged actions onto the master product. Triggered by `POST /admin/product-changes/:id/confirm`, and internally by `autoConfirmProductChangeWorkflow`. Emits `product-change.confirmed` with one `{ id }` per change.
-
-## Usage
-
-```ts
-import { confirmProductChangeWorkflow } from "@mercurjs/core/workflows"
-
-await confirmProductChangeWorkflow(container).run({
-  input: {
-    ids: ["prch_01H..."],
-    confirmed_by: "user_01H...",
-  },
-})
-```
-
-## Input
-
-<ParamField body="ids" type="string[]" required>
-  Ids of the product changes to confirm. Each must exist and be in a confirmable (`pending`) state.
-</ParamField>
-
-<ParamField body="confirmed_by" type="string">
-  Actor id recorded as the confirmer on each change.
-</ParamField>
-
-<ParamField body="internal_note" type="string">
-  Operator-only note stored on each confirmed change.
-</ParamField>
-
-<ParamField body="external_note" type="string">
-  Vendor-facing note stored on each confirmed change.
-</ParamField>
-
-<ParamField body="additional_data" type="object">
-  Arbitrary data forwarded to the `productChangeConfirmed` hook.
-</ParamField>
-
-## Result
-
-<ResponseField name="result" type="void">
-  Returns nothing; the changes are confirmed and their actions applied in place.
-</ResponseField>
-
-## Hooks
-
-<ResponseField name="validate" type="hook">
-  Runs first with `{ input }` — use it to block confirmation of specific changes.
-</ResponseField>
-
-<ResponseField name="productChangeConfirmed" type="hook">
-  Runs after actions are applied with `{ ids, additional_data }`.
-</ResponseField>

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

@@ -1,72 +0,0 @@
----
-title: "createProductChangeWorkflow"
-description: "Create ProductChange records after validating no pending change exists per product."
----
-
-Creates one or more `ProductChange` records — the staging entity for vendor edits on shared master products. Validates that none of the referenced products already has a `pending` change before inserting. Emits `product-change.created` with one `{ id }` entry per change. Actions are attached separately (see `stageProductChangeWorkflow` for the combined flow).
-
-## Usage
-
-```ts
-import { createProductChangeWorkflow } from "@mercurjs/core/workflows"
-
-const { result } = await createProductChangeWorkflow(container).run({
-  input: {
-    changes: [
-      { product_id: "prod_01H...", created_by: "sel_01H..." },
-    ],
-  },
-})
-```
-
-## Input
-
-<ParamField body="changes" type="CreateProductChangeDTO[]" required>
-  Changes to create.
-  <Expandable title="properties">
-    <ParamField body="product_id" type="string" required>
-      Id of the product the change targets. Must not already have a pending change.
-    </ParamField>
-    <ParamField body="status" type="ProductChangeStatus">
-      One of `pending`, `confirmed`, `declined`, `canceled`; audit-trail rows are created already `confirmed`.
-    </ParamField>
-    <ParamField body="created_by" type="string">
-      Actor id who authored the change.
-    </ParamField>
-    <ParamField body="internal_note" type="string">
-      Operator-only note.
-    </ParamField>
-    <ParamField body="external_note" type="string">
-      Vendor-facing note.
-    </ParamField>
-    <ParamField body="confirmed_by" type="string">
-      Confirming actor id, for pre-confirmed rows.
-    </ParamField>
-    <ParamField body="confirmed_at" type="Date">
-      Confirmation timestamp, for pre-confirmed rows.
-    </ParamField>
-    <ParamField body="metadata" type="object">
-      Arbitrary key-value data stored on the change.
-    </ParamField>
-  </Expandable>
-</ParamField>
-
-<ParamField body="additional_data" type="object">
-  Arbitrary data forwarded to the `productChangeCreated` hook.
-</ParamField>
-
-## Result
-
-<ResponseField name="result" type="ProductChangeDTO[]">
-  The created change records with ids, statuses, and timestamps.
-</ResponseField>
-
-## Hooks
-
-<ResponseField name="validate" type="hook">
-  Runs first with `{ input }` — use it to reject invalid payloads before creation.
-</ResponseField>
-
-<ResponseField name="productChangeCreated" type="hook">
-  Runs after creation with `{ changes, additional_data }`.
-</ResponseField>

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

@@ -1,54 +0,0 @@
----
-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

@@ -1,75 +0,0 @@
----
-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

@@ -1,36 +0,0 @@
----
-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>
-
-<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
-
-- `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

@@ -1,59 +0,0 @@
----
-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

@@ -1,22 +0,0 @@
----
-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>