Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
import type { ValidationErrorDetail } from '@spree/admin-sdk'
import { SpreeError } from '@spree/admin-sdk'
import i18n from 'i18next'
import type { FieldValues, Path, UseFormSetError } from 'react-hook-form'
/**
* Text for one validation failure, in the admin's own language.
*
* Server codes live under `admin.validation.codes`, apart from the client-side
* keys the forms' own schemas read (`admin.validation.required`, …). The two
* vocabularies overlap — Rails' `required` is a missing association, the
* client's is an empty input — so they cannot share a namespace.
*
* The Admin API reports the Rails error `code` and the values the validation
* interpolates, so the copy comes from the dashboard's locale files rather
* than from a message the server resolved in the store's locale. Keys are
* tried per-attribute first (`admin.validation.codes.quantity.greater_than`), then
* generally (`admin.validation.codes.greater_than`); the server's `message` is the
* fallback, which is what an extension's own error code gets.
*
* @param field the attribute the failure is attached to
* @param entry the API's detail entry, or a plain string from an older payload
* @returns the message to render
*/
function resolveDetailMessage(field: string, entry: string | ValidationErrorDetail): string {
if (typeof entry === 'string') return entry
const { code, message, specific, ...interpolation } = entry
if (!code) return message
// Per-attribute first: `admin.validation.codes.url.invalid` is written for this
// one field and beats both the generic key and the server.
const attributeKey = `admin.validation.codes.${field}.${code}`
if (i18n.exists(attributeKey)) return i18n.t(attributeKey, interpolation)
// `specific` means the model overrode the code's own wording with something
// more useful — the webhook URL validation reports `invalid` but answers
// "must be a valid http or https URL". Translating the code would throw
// that away. The server decides this, because only it can compare against
// the code's default in the locale the message was resolved in.
if (specific) return message
const genericKey = `admin.validation.codes.${code}`
return i18n.exists(genericKey) ? i18n.t(genericKey, interpolation) : message
}
/**
* Whether {@link resolveDetailMessage} will translate this entry rather than
* fall back to the server's message.
*
* A per-attribute key is written for this one field and wins even over a
* message the model worded itself; the generic key only applies when the
* server did not mark the message as its own.
*/
function hasTranslation(field: string, entry: ValidationErrorDetail): boolean {
if (i18n.exists(`admin.validation.codes.${field}.${entry.code}`)) return true
if (entry.specific) return false
return i18n.exists(`admin.validation.codes.${entry.code}`)
}
/**
* The failure summary in the admin's own language: "Name can't be blank,
* Quantity must be greater than 0", assembled from the translated entries and
* the attribute names the dashboard already publishes.
*
* Returns null when any entry has no translation, in which case the server's
* sentence is left alone rather than half-rebuilt.
*
* @param details the API's per-attribute failures
* @returns the assembled summary, or null to keep the server's
*/
function translatedSummary(
details: Record<string, Array<string | ValidationErrorDetail>>,
fieldAliases?: Record<string, string>,
): string | null {
const sentences: string[] = []
for (const [field, entries] of Object.entries(details)) {
for (const entry of entries ?? []) {
// A plain string predates the coded shape and carries nothing to
// translate; a missing code is a message added as bare text.
if (typeof entry === 'string' || !entry.code) return null
// Resolved exactly as the field error is, so the banner and the input
// beneath it never disagree, and skipped only when that resolution
// would fall through to the server's own sentence.
if (!hasTranslation(field, entry)) return null
const labelField = fieldAliases?.[field] ?? field
sentences.push(`${attributeLabel(labelField)} ${resolveDetailMessage(field, entry)}`.trim())
}
}
return sentences.length > 0 ? sentences.join(', ') : null
}
/**
* Display name for an attribute, from the same keys the forms label their
* inputs with. Falls back to the humanized attribute, which is what Rails
* would have produced anyway.
*/
function attributeLabel(field: string): string {
const key = `admin.fields.${field}.label`
if (i18n.exists(key)) return i18n.t(key)
if (field === 'base') return ''
return field.replace(/_/g, ' ').replace(/^./, (c) => c.toUpperCase())
}
/**
* Map a thrown error from a Spree Admin API mutation onto a react-hook-form
* instance. Two things happen on every call:
*
* 1. The server's top-level `error.message` (e.g. "Code can't be blank, Name
* can't be blank") is set on `formState.errors.root` so `<FormError>`
* always renders the full failure summary — even when individual fields
* aren't rendered (nested rules, useFieldArray rows, validations on
* associations).
* 2. Per-key entries from `error.details` are also set as per-field errors
* for any key that names a top-level flat attribute (`code`, `name`,
* `expires_at`). Nested or dotted keys (`promotion_rules.base`, `rules`
* on a useFieldArray, `line_items.0.quantity`) only contribute to the
* root summary — we don't pretend to know which of those have rendered
* inputs, and "silent" is the worst outcome.
*
* Return value:
* - `true` → the error was rendered into the form, the caller may suppress
* its toast
* - `false` → not a SpreeError (network / programming bug). Caller should
* log + toast as usual.
*
* Usage:
*
* ```ts
* const create = useCreateThing()
*
* async function onSubmit(values: FormValues) {
* try {
* await create.mutateAsync(values)
* onSuccess()
* } catch (err) {
* if (!mapSpreeErrorsToForm(err, form.setError)) throw err
* }
* }
* ```
*
* Server response shape (from `Spree::Api::V3::ErrorHandler#render_validation_error`):
*
* ```json
* { "error": {
* "code": "validation_error",
* "message": "Code can't be blank, Quantity must be greater than 0",
* "details": {
* "code": [{ "code": "blank", "message": "can't be blank" }],
* "quantity": [{ "code": "greater_than", "message": "must be greater than 0", "count": 0 }]
* }
* } }
* ```
*
* Each entry's `code` is translated from the dashboard's own locale files so
* the admin reads their interface language rather than the store's; `message`
* is the fallback for codes with no translation.
*
* `details` keys are AR attribute names. `<form-field>.base` is AR's
* record-level errors collection on a nested association — we treat both
* the bare `base` key and any `*.base` key as record-level and route them
* to root.
*/
export interface MapSpreeErrorsToFormOptions<TFieldValues extends FieldValues> {
/**
* Rails attribute names that differ from the form field the input is bound
* to. Address validation reports on `state`; the dashboard writes
* `state_code`.
*/
fieldAliases?: Partial<Record<string, Path<TFieldValues>>>
}
export function mapSpreeErrorsToForm<TFieldValues extends FieldValues>(
error: unknown,
setError: UseFormSetError<TFieldValues>,
options?: MapSpreeErrorsToFormOptions<TFieldValues>,
): boolean {
if (!(error instanceof SpreeError)) return false
const { details, message } = error
const fieldAliases = options?.fieldAliases as Record<string, string> | undefined
// The summary banner is the line a merchant actually reads, so it follows
// their interface language too. It is rebuilt from the translated entries
// when every one of them translated; a single untranslated code means the
// server's own sentence is still the more complete summary, and it stays.
const summary = (details && translatedSummary(details, fieldAliases)) || message
if (summary) {
setError('root' as Path<TFieldValues>, { type: 'server', message: summary })
}
if (!details) return true
// Per-field errors. Each detail value is `string[]` (one Rails error per
// entry). Only top-level flat keys get set as per-field errors; nested
// keys (`promotion_rules.base`, `rules`, `line_items.0.x`) stay on root.
//
// We're conservative on purpose: there's no way to know at this layer
// whether a given path has a rendered input, so anything that smells
// nested or associative falls back to the root summary that we already
// set above. Silently dropping errors onto unrendered field paths is a
// worse failure mode than redundant root messages.
for (const [field, entries] of Object.entries(details)) {
if (!entries?.length) continue
const formField = (fieldAliases?.[field] ?? field) as string
if (!isRenderableFieldKey(formField)) continue
setError(formField as Path<TFieldValues>, {
type: 'server',
message: entries.map((entry) => resolveDetailMessage(field, entry)).join(', '),
})
}
return true
}
// `base` (bare) and `*.base` are AR's record-level errors. `*.<n>.*` is an
// association/collection index path. Anything with `.` is too risky to set
// as a top-level RHF path — it'd either create a phantom nested error or
// silently miss a rendered field. Stick to flat snake_case keys.
function isRenderableFieldKey(key: string): boolean {
if (key === 'base') return false
if (key.includes('.')) return false
return true
}