@open-mercato/ui 0.4.2-canary-c02407ff85

package/src/backend/utils/customFieldDefs.ts

@@ -0,0 +1,245 @@
+import * as React from 'react'
+import { useQuery, type UseQueryResult, type QueryClient } from '@tanstack/react-query'
+import { readApiResultOrThrow } from './apiCall'
+import type { CustomFieldOptionDto } from '@open-mercato/shared/modules/entities/options'
+
+export type CustomFieldDefDto = {
+  entityId?: string
+  key: string
+  kind: string
+  label?: string
+  description?: string
+  options?: CustomFieldOptionDto[]
+  optionsUrl?: string
+  multi?: boolean
+  filterable?: boolean
+  formEditable?: boolean
+  listVisible?: boolean
+  editor?: string
+  input?: string
+  priority?: number
+  fieldset?: string
+  group?: { code: string; title?: string; hint?: string }
+  // attachments-specific config
+  maxAttachmentSizeMb?: number
+  acceptExtensions?: string[]
+  // optional validation rules
+  validation?: Array<
+    | { rule: 'required'; message: string }
+    | { rule: 'date'; message: string }
+    | { rule: 'integer'; message: string }
+    | { rule: 'float'; message: string }
+    | { rule: 'lt' | 'lte' | 'gt' | 'gte'; param: number; message: string }
+    | { rule: 'eq' | 'ne'; param: any; message: string }
+    | { rule: 'regex'; param: string; message: string }
+  >
+  dictionaryId?: string
+  dictionaryInlineCreate?: boolean
+}
+
+export type CustomFieldsetGroupDto = {
+  code: string
+  title?: string
+  hint?: string
+}
+
+export type CustomFieldsetDto = {
+  code: string
+  label: string
+  icon?: string
+  description?: string
+  groups?: CustomFieldsetGroupDto[]
+}
+
+export type CustomFieldDefinitionsPayload = {
+  items?: CustomFieldDefDto[]
+  fieldsetsByEntity?: Record<string, CustomFieldsetDto[]>
+  entitySettings?: Record<string, { singleFieldsetPerRecord?: boolean }>
+}
+
+export function normalizeEntityIds(entityIds: string | string[] | null | undefined): string[] {
+  if (entityIds == null) return []
+  const list = Array.isArray(entityIds) ? entityIds : [entityIds]
+  const dedup = new Set<string>()
+  const normalized: string[] = []
+  for (const raw of list) {
+    const trimmed = String(raw ?? '').trim()
+    if (!trimmed || dedup.has(trimmed)) continue
+    dedup.add(trimmed)
+    normalized.push(trimmed)
+  }
+  return normalized
+}
+
+export type CustomFieldDefinitionQueryOptions = {
+  fieldset?: string
+}
+
+function buildDefinitionsQuery(entityIds: string[], options?: CustomFieldDefinitionQueryOptions): string {
+  const params = new URLSearchParams()
+  entityIds.forEach((id) => {
+    if (id) params.append('entityId', id)
+  })
+  if (options?.fieldset) params.set('fieldset', options.fieldset)
+  return params.toString()
+}
+
+type CustomFieldDefinitionsResponse = CustomFieldDefinitionsPayload
+
+function normalizeRecord<T>(value: unknown): Record<string, T[]> {
+  if (!value || typeof value !== 'object') return {}
+  const out: Record<string, T[]> = {}
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    if (!Array.isArray(raw)) continue
+    out[key] = raw as T[]
+  }
+  return out
+}
+
+function preparePayload(data: CustomFieldDefinitionsResponse | null | undefined): CustomFieldDefinitionsPayload {
+  const items = Array.isArray(data?.items) ? [...data!.items] : []
+  items.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0))
+  const fieldsetsByEntity = normalizeRecord<CustomFieldsetDto>(data?.fieldsetsByEntity)
+  const entitySettings = (data?.entitySettings && typeof data.entitySettings === 'object'
+    ? data.entitySettings
+    : {}) as CustomFieldDefinitionsPayload['entitySettings']
+  return { items, fieldsetsByEntity, entitySettings }
+}
+
+async function readDefinitionsViaFetch(
+  entityIds: string[],
+  fetchImpl: typeof fetch,
+  options?: CustomFieldDefinitionQueryOptions,
+): Promise<CustomFieldDefinitionsPayload> {
+  const query = buildDefinitionsQuery(entityIds, options)
+  const res = await fetchImpl(`/api/entities/definitions?${query}`, {
+    headers: { 'content-type': 'application/json' },
+  })
+  const data = await res.json().catch(() => ({ items: [] }))
+  return preparePayload(data)
+}
+
+async function readDefinitionsViaApi(entityIds: string[], options?: CustomFieldDefinitionQueryOptions): Promise<CustomFieldDefinitionsPayload> {
+  const query = buildDefinitionsQuery(entityIds, options)
+  const payload = await readApiResultOrThrow<CustomFieldDefinitionsResponse>(
+    `/api/entities/definitions?${query}`,
+    { headers: { 'content-type': 'application/json' } },
+    {
+      errorMessage: 'Failed to load custom field definitions',
+      fallback: { items: [] },
+    },
+  )
+  return preparePayload(payload)
+}
+
+export async function fetchCustomFieldDefinitionsPayload(
+  entityIds: string | string[],
+  fetchImpl?: typeof fetch,
+  options?: CustomFieldDefinitionQueryOptions,
+): Promise<CustomFieldDefinitionsPayload> {
+  const filtered = normalizeEntityIds(entityIds)
+  if (!filtered.length) return { items: [] }
+  return fetchImpl
+    ? await readDefinitionsViaFetch(filtered, fetchImpl, options)
+    : await readDefinitionsViaApi(filtered, options)
+}
+
+export async function fetchCustomFieldDefs(
+  entityIds: string | string[],
+  fetchImpl?: typeof fetch,
+  options?: CustomFieldDefinitionQueryOptions,
+): Promise<CustomFieldDefDto[]> {
+  const payload = await fetchCustomFieldDefinitionsPayload(entityIds, fetchImpl, options)
+  return payload.items ?? []
+}
+
+export type UseCustomFieldDefsOptions<TData = CustomFieldDefDto[]> = {
+  enabled?: boolean
+  staleTime?: number
+  gcTime?: number
+  /** @deprecated Custom fetch implementations are no longer needed. */
+  fetchImpl?: typeof fetch
+  keyExtras?: Array<string | number | boolean | null | undefined>
+  fieldset?: string
+  select?: (data: CustomFieldDefDto[]) => TData
+}
+
+export function useCustomFieldDefs<TData = CustomFieldDefDto[]>(
+  entityIds: string | string[] | null | undefined,
+  options: UseCustomFieldDefsOptions<TData> = {}
+): UseQueryResult<TData> {
+  const {
+    enabled: enabledOption = true,
+    staleTime,
+    gcTime,
+    keyExtras,
+    fetchImpl,
+    fieldset,
+  } = options
+  const normalizedIds = React.useMemo(() => normalizeEntityIds(entityIds), [entityIds])
+  const idsSignature = React.useMemo(() => JSON.stringify(normalizedIds), [normalizedIds])
+  const extrasSignature = React.useMemo(() => JSON.stringify(keyExtras ?? []), [keyExtras])
+  const normalizedFieldset = typeof fieldset === 'string' && fieldset.trim().length ? fieldset.trim() : null
+  const queryKey = React.useMemo(
+    () => ['customFieldDefs', ...(keyExtras ?? []), ...normalizedIds, `fieldset:${normalizedFieldset ?? 'default'}`],
+    [idsSignature, extrasSignature, normalizedFieldset]
+  )
+  const enabled = enabledOption && normalizedIds.length > 0
+
+  return useQuery<CustomFieldDefDto[], Error, TData>({
+    queryKey,
+    queryFn: () =>
+      fetchCustomFieldDefs(
+        normalizedIds,
+        fetchImpl,
+        normalizedFieldset ? { fieldset: normalizedFieldset } : undefined
+      ),
+    enabled,
+    staleTime: staleTime ?? 5 * 60 * 1000,
+    gcTime: gcTime ?? 30 * 60 * 1000,
+    select: options.select,
+  })
+}
+
+export type CustomFieldVisibility = 'list' | 'form' | 'filter'
+
+export function isDefVisible(def: CustomFieldDefDto, mode: CustomFieldVisibility): boolean {
+  switch (mode) {
+    case 'list':
+      return def.listVisible !== false
+    case 'form':
+      return def.formEditable !== false
+    case 'filter':
+      return !!def.filterable
+    default:
+      return true
+  }
+}
+
+export function filterCustomFieldDefs(defs: CustomFieldDefDto[], mode: CustomFieldVisibility): CustomFieldDefDto[] {
+  return defs
+    .filter((d) => isDefVisible(d, mode))
+    .sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0))
+}
+
+export async function invalidateCustomFieldDefs(
+  queryClient: QueryClient,
+  entityIds?: string | string[] | null,
+): Promise<void> {
+  const normalizedIds = normalizeEntityIds(entityIds)
+  const targetPrefixes = new Set(['customFieldDefs', 'customFieldForms', 'dealFormFields'])
+  if (!normalizedIds.length) {
+    await queryClient.invalidateQueries({
+      predicate: (query) => Array.isArray(query.queryKey) && typeof query.queryKey[0] === 'string' && targetPrefixes.has(query.queryKey[0] as string),
+    })
+    return
+  }
+  await queryClient.invalidateQueries({
+    predicate: (query) => {
+      if (!Array.isArray(query.queryKey)) return false
+      const [prefix] = query.queryKey
+      if (typeof prefix !== 'string' || !targetPrefixes.has(prefix)) return false
+      return normalizedIds.every((id) => query.queryKey.includes(id))
+    },
+  })
+}

package/src/backend/utils/customFieldFilters.ts

@@ -0,0 +1,145 @@
+import * as React from 'react'
+import { useCustomFieldDefs, type UseCustomFieldDefsOptions } from './customFieldDefs'
+import { Filter } from '@open-mercato/shared/lib/query/types'
+import type { FilterDef } from '../FilterOverlay'
+import type { CustomFieldDefDto } from './customFieldDefs'
+export type { CustomFieldDefDto }
+import { filterCustomFieldDefs, fetchCustomFieldDefs as loadCustomFieldDefs } from './customFieldDefs'
+import { type UseQueryResult } from '@tanstack/react-query'
+import { apiCall } from './apiCall'
+import { CURRENCY_OPTIONS_URL } from '@open-mercato/shared/modules/entities/kinds'
+
+function buildOptionsUrl(base: string, query?: string): string {
+  if (!query) return base
+  try {
+    const isAbsolute = /^([a-z][a-z\d+\-.]*:)?\/\//i.test(base)
+    const origin = typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
+    const url = isAbsolute ? new URL(base) : new URL(base, origin)
+    if (!url.searchParams.has('query')) url.searchParams.append('query', query)
+    if (!url.searchParams.has('q')) url.searchParams.append('q', query)
+    if (isAbsolute) return url.toString()
+    return `${url.pathname}${url.search}`
+  } catch {
+    const sep = base.includes('?') ? '&' : '?'
+    if (base.includes('query=')) return `${base}${sep}q=${encodeURIComponent(query)}`
+    return `${base}${sep}query=${encodeURIComponent(query)}`
+  }
+}
+
+type OptionsResponse = { items?: unknown[] }
+
+async function loadRemoteOptions(url: string): Promise<Array<{ value: string; label: string }>> {
+  try {
+    const call = await apiCall<OptionsResponse>(url, undefined, { fallback: { items: [] } })
+    if (!call.ok) return []
+    const payload = call.result ?? { items: [] }
+    const items = Array.isArray(payload?.items) ? payload.items : []
+    return items.map((it: any) => ({
+      value: String(it?.value ?? it),
+      label: String(it?.label ?? it?.value ?? it),
+    }))
+  } catch {
+    return []
+  }
+}
+
+type RawOption = string | number | { value?: unknown; label?: unknown }
+
+function normalizeOptions(options?: RawOption[]): Array<{ value: string; label: string }> {
+  if (!Array.isArray(options)) return []
+  return options.map((option) => {
+    if (option && typeof option === 'object' && 'value' in option) {
+      const rawValue = (option as any).value
+      const rawLabel = (option as any).label ?? rawValue
+      const value = String(rawValue)
+      const label = typeof rawLabel === 'string' ? rawLabel : String(rawLabel)
+      return { value, label }
+    }
+    const value = String(option)
+    return { value, label: value.charAt(0).toUpperCase() + value.slice(1) }
+  })
+}
+
+export function buildFilterDefsFromCustomFields(defs: CustomFieldDefDto[]): FilterDef[] {
+  const f: FilterDef[] = []
+  const visible = filterCustomFieldDefs(defs, 'filter')
+  const seenKeys = new Set<string>() // case-insensitive de-dupe by key
+  for (const d of visible) {
+    const keyLower = String(d.key).toLowerCase()
+    if (seenKeys.has(keyLower)) continue
+    seenKeys.add(keyLower)
+    const id = `cf_${d.key}`
+    const label = d.label || d.key
+    if (d.kind === 'boolean') {
+      f.push({ id, label, type: 'checkbox' })
+    } else if (d.kind === 'select' || d.kind === 'currency' || d.kind === 'relation' || d.kind === 'dictionary') {
+      const options = normalizeOptions(d.options)
+      const base: FilterDef = { id: d.multi ? `${id}In` : id, label, type: 'select', multiple: !!d.multi, options }
+      // When optionsUrl is provided, allow async options loading for filters too
+      const optionsUrl = d.kind === 'currency' ? CURRENCY_OPTIONS_URL : d.optionsUrl
+      if (optionsUrl) {
+        ;(base as FilterDef).loadOptions = async (query?: string) => {
+          const url = buildOptionsUrl(optionsUrl, query)
+          return loadRemoteOptions(url)
+        }
+      }
+      f.push(base)
+    } else if (d.kind === 'text' && d.multi) {
+      // Multi-text custom field → use tags input in filters
+      const base: FilterDef = {
+        id: `${id}In`,
+        label,
+        type: 'tags',
+        // If static options provided, pass them for suggestions
+        options: normalizeOptions(d.options),
+      } as any
+      // Enable async suggestions when optionsUrl provided
+      if (d.optionsUrl) {
+        ;(base as any).loadOptions = async (query?: string) => {
+          const url = buildOptionsUrl(d.optionsUrl!, query)
+          return loadRemoteOptions(url)
+        }
+      }
+      f.push(base)
+    } else {
+      f.push({ id, label, type: 'text' })
+    }
+  }
+  // De-duplicate by id in case of overlaps; keep first occurrence
+  const out: FilterDef[] = []
+  const seen = new Set<string>()
+  for (const item of f) {
+    if (seen.has(item.id)) continue
+    seen.add(item.id)
+    out.push(item)
+  }
+  // Preserve the original visible order (already sorted by priority) by mapping back
+  const order = new Map(visible.map((v, idx) => [v.key, idx]))
+  out.sort((a, b) => (order.get(a.id.replace(/^cf_/, '').replace(/In$/, '')) ?? 0) - (order.get(b.id.replace(/^cf_/, '').replace(/In$/, '')) ?? 0))
+  return out
+}
+
+export async function fetchCustomFieldFilterDefs(
+  entityIds: string | string[],
+  fetchImpl?: typeof fetch,
+  options?: { fieldset?: string },
+): Promise<FilterDef[]> {
+  const defs: CustomFieldDefDto[] = await loadCustomFieldDefs(
+    entityIds,
+    fetchImpl,
+    options?.fieldset ? { fieldset: options.fieldset } : undefined,
+  )
+  return buildFilterDefsFromCustomFields(defs)
+}
+
+export function useCustomFieldFilterDefs(
+  entityIds: string | string[] | null | undefined,
+  options: UseCustomFieldDefsOptions<FilterDef[]> = {}
+): UseQueryResult<FilterDef[]> {
+  const { select, ...rest } = options
+  const selectFn = React.useCallback(
+    (defs: CustomFieldDefDto[]) => (select ? select(defs) : buildFilterDefsFromCustomFields(defs)),
+    [select]
+  )
+  return useCustomFieldDefs<FilterDef[]>(entityIds, { ...rest, select: selectFn })
+}

package/src/backend/utils/customFieldForms.ts

@@ -0,0 +1,196 @@
+import type { CrudField } from '../CrudForm'
+import type {
+  CustomFieldDefDto,
+  CustomFieldDefinitionsPayload,
+} from './customFieldDefs'
+import {
+  filterCustomFieldDefs,
+  fetchCustomFieldDefs,
+  fetchCustomFieldDefinitionsPayload,
+} from './customFieldDefs'
+import { FieldRegistry, loadGeneratedFieldRegistrations } from '../fields/registry'
+import { apiCall } from './apiCall'
+import { normalizeCustomFieldOptions } from '@open-mercato/shared/modules/entities/options'
+import { CURRENCY_OPTIONS_URL } from '@open-mercato/shared/modules/entities/kinds'
+
+let registryReady: Promise<void> | null = null
+
+async function ensureFieldRegistryReady() {
+  if (!registryReady) {
+    registryReady = loadGeneratedFieldRegistrations().catch((err) => {
+      registryReady = null
+      throw err
+    })
+  }
+  await registryReady
+}
+
+function buildOptionsUrl(base: string, query?: string): string {
+  if (!query) return base
+  try {
+    const isAbsolute = /^([a-z][a-z\d+\-.]*:)?\/\//i.test(base)
+    const origin = typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
+    const url = isAbsolute ? new URL(base) : new URL(base, origin)
+    if (!url.searchParams.has('query')) url.searchParams.append('query', query)
+    if (!url.searchParams.has('q')) url.searchParams.append('q', query)
+    if (isAbsolute) return url.toString()
+    return `${url.pathname}${url.search}`
+  } catch {
+    const sep = base.includes('?') ? '&' : '?'
+    if (base.includes('query=')) return `${base}${sep}q=${encodeURIComponent(query)}`
+    return `${base}${sep}query=${encodeURIComponent(query)}`
+  }
+}
+
+type OptionsResponse = { items?: unknown[] }
+
+async function loadRemoteOptions(url: string): Promise<Array<{ value: string; label: string }>> {
+  try {
+    const call = await apiCall<OptionsResponse>(url, undefined, { fallback: { items: [] } })
+    if (!call.ok) return []
+    const payload = call.result ?? { items: [] }
+    const items = Array.isArray(payload?.items) ? payload.items : []
+    return items.map((it: any) => ({
+      value: String(it?.value ?? it),
+      label: String(it?.label ?? it?.value ?? it),
+    }))
+  } catch {
+    return []
+  }
+}
+
+export function buildFormFieldFromCustomFieldDef(
+  def: CustomFieldDefDto,
+  opts?: { bareIds?: boolean }
+): CrudField | null {
+  const id = opts?.bareIds ? def.key : `cf_${def.key}`
+  const label = def.label || def.key
+  const required = Array.isArray((def as any).validation)
+    ? ((def as any).validation as any[]).some((rule) => rule && rule.rule === 'required')
+    : false
+
+  switch (def.kind) {
+    case 'boolean':
+      return { id, label, type: 'checkbox', description: def.description, required }
+    case 'integer':
+    case 'float':
+      return { id, label, type: 'number', description: def.description, required }
+    case 'multiline': {
+      let editor: 'simple' | 'uiw' | 'html' = 'uiw'
+      if (def.editor === 'simpleMarkdown') editor = 'simple'
+      else if (def.editor === 'htmlRichText') editor = 'html'
+      return { id, label, type: 'richtext', description: def.description, editor, required }
+    }
+    case 'select':
+    case 'currency':
+    case 'relation':
+      return {
+        id,
+        label,
+        type: 'select',
+        description: def.description,
+        options: normalizeCustomFieldOptions(def.options || []).map((option) => ({
+          value: option.value,
+          label: option.label,
+        })),
+        multiple: !!def.multi,
+        required,
+        ...(def.kind === 'currency'
+          ? {
+              loadOptions: async (query?: string) => {
+                const url = buildOptionsUrl(CURRENCY_OPTIONS_URL, query)
+                return loadRemoteOptions(url)
+              },
+            }
+          : def.optionsUrl
+          ? {
+              loadOptions: async (query?: string) => {
+                const url = buildOptionsUrl(def.optionsUrl!, query)
+                return loadRemoteOptions(url)
+              },
+            }
+          : {}),
+        ...(def.multi && def.input === 'listbox' ? ({ listbox: true } as any) : {}),
+      }
+    default: {
+      if (def.kind === 'text' && def.multi) {
+        const base: any = { id, label, type: 'tags', description: def.description, required }
+        const resolvedOptions = normalizeCustomFieldOptions(def.options || [])
+        if (resolvedOptions.length > 0) {
+          base.options = resolvedOptions.map((option) => ({ value: option.value, label: option.label }))
+        }
+        if (def.optionsUrl) {
+          base.loadOptions = async (query?: string) => {
+            const url = buildOptionsUrl(def.optionsUrl!, query)
+            return loadRemoteOptions(url)
+          }
+        }
+        return base
+      }
+      if (def.kind === 'text' && typeof def.editor === 'string' && def.editor) {
+        let editor: 'simple' | 'uiw' | 'html' = 'uiw'
+        if (def.editor === 'simpleMarkdown') editor = 'simple'
+        else if (def.editor === 'htmlRichText') editor = 'html'
+        return { id, label, type: 'richtext', description: def.description, editor, required }
+      }
+      const input = FieldRegistry.getInput(def.kind)
+      if (input) {
+        return {
+          id,
+          label,
+          type: 'custom',
+          required,
+          description: def.description,
+          component: (props) => input({ ...props, def }),
+        }
+      }
+      return { id, label, type: 'text', description: def.description, required }
+    }
+  }
+}
+
+export function buildFormFieldsFromCustomFields(
+  defs: CustomFieldDefDto[],
+  opts?: { bareIds?: boolean }
+): CrudField[] {
+  const fields: CrudField[] = []
+  const visible = filterCustomFieldDefs(defs, 'form')
+  const seenKeys = new Set<string>()
+  for (const def of visible) {
+    const keyLower = String(def.key).toLowerCase()
+    if (seenKeys.has(keyLower)) continue
+    seenKeys.add(keyLower)
+    const field = buildFormFieldFromCustomFieldDef(def, opts)
+    if (field) fields.push(field)
+  }
+  return fields
+}
+
+export async function fetchCustomFieldFormStructure(
+  entityIds: string | string[],
+  fetchImpl?: typeof fetch,
+  options?: { bareIds?: boolean },
+): Promise<{ fields: CrudField[]; definitions: CustomFieldDefDto[]; metadata: CustomFieldDefinitionsPayload }> {
+  await ensureFieldRegistryReady()
+  const metadata = await fetchCustomFieldDefinitionsPayload(entityIds, fetchImpl)
+  const definitions = Array.isArray(metadata.items) ? metadata.items : []
+  const fields = buildFormFieldsFromCustomFields(definitions, options)
+  return { fields, definitions, metadata }
+}
+
+export async function fetchCustomFieldFormFields(
+  entityIds: string | string[],
+  fetchImpl?: typeof fetch,
+  options?: { bareIds?: boolean },
+): Promise<CrudField[]> {
+  const { fields } = await fetchCustomFieldFormStructure(entityIds, fetchImpl, options)
+  return fields
+}
+
+export async function fetchCustomFieldFormFieldsWithDefinitions(
+  entityIds: string | string[],
+  fetchImpl?: typeof fetch,
+  options?: { bareIds?: boolean },
+): Promise<{ fields: CrudField[]; definitions: CustomFieldDefDto[]; metadata: CustomFieldDefinitionsPayload }> {
+  return fetchCustomFieldFormStructure(entityIds, fetchImpl, options)
+}

package/src/backend/utils/customFieldValues.ts

@@ -0,0 +1,41 @@
+export type CollectCustomFieldOptions = {
+  prefixes?: string[]
+  stripPrefix?: boolean
+  transform?: (value: unknown, fieldId: string, rawKey: string) => unknown
+  accept?: (fieldId: string, rawKey: string, value: unknown) => boolean
+  omitUndefined?: boolean
+}
+
+const DEFAULT_PREFIXES = ['cf_', 'cf:']
+
+export function collectCustomFieldValues(
+  values: Record<string, unknown>,
+  options: CollectCustomFieldOptions = {},
+): Record<string, unknown> {
+  const {
+    prefixes = DEFAULT_PREFIXES,
+    stripPrefix = true,
+    transform,
+    accept,
+    omitUndefined = true,
+  } = options
+
+  const result: Record<string, unknown> = {}
+
+  for (const [rawKey, rawValue] of Object.entries(values)) {
+    const prefix = prefixes.find((candidate) => rawKey.startsWith(candidate))
+    if (!prefix) continue
+
+    const fieldId = stripPrefix ? rawKey.slice(prefix.length) : rawKey
+    if (!fieldId) continue
+
+    if (accept && !accept(fieldId, rawKey, rawValue)) continue
+
+    const nextValue = transform ? transform(rawValue, fieldId, rawKey) : rawValue
+    if (omitUndefined && nextValue === undefined) continue
+
+    result[fieldId] = nextValue
+  }
+
+  return result
+}

package/src/backend/utils/flash.ts

@@ -0,0 +1,17 @@
+export type FlashType = 'success' | 'error' | 'warning' | 'info'
+
+// Append flash message and type to a URL (relative or absolute) and return a relative URL string.
+export function withFlash(url: string, message: string, type: FlashType = 'success'): string {
+  const base = typeof window !== 'undefined' && window.location ? window.location.origin : 'http://localhost'
+  const u = new URL(url, base)
+  u.searchParams.set('flash', message)
+  u.searchParams.set('type', type)
+  const qs = u.searchParams.toString()
+  return `${u.pathname}${qs ? `?${qs}` : ''}`
+}
+
+// Helper to push a URL with flash via Next.js router
+export function pushWithFlash(router: { push: (href: string) => any }, url: string, message: string, type: FlashType = 'success') {
+  router.push(withFlash(url, message, type))
+}
+