@spree/dashboard-core 0.13.1 → 1.0.0-beta.1

package/src/lib/date-presets.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { matchDatePreset, resolveDatePreset } from './date-presets'
+
+// A fixed instant with a deliberately awkward property: 23:30 UTC on the 15th
+// is already the 16th in Sydney and still the 15th in Los Angeles. Every
+// assertion below turns on which calendar the range is computed against.
+const INSTANT = new Date('2026-03-15T23:30:00Z')
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(INSTANT)
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('resolveDatePreset', () => {
+  it('reads "today" on the store\'s calendar, not the viewer\'s', () => {
+    // Same instant, three zones, three different answers for "today". This is
+    // the whole reason the timezone is threaded through.
+    expect(resolveDatePreset('today', 'America/Los_Angeles')).toEqual({
+      from: '2026-03-15',
+      to: '2026-03-15',
+    })
+    expect(resolveDatePreset('today', 'UTC')).toEqual({ from: '2026-03-15', to: '2026-03-15' })
+    expect(resolveDatePreset('today', 'Australia/Sydney')).toEqual({
+      from: '2026-03-16',
+      to: '2026-03-16',
+    })
+  })
+
+  it('counts "last 7 days" inclusively, so it spans exactly 7 dates', () => {
+    expect(resolveDatePreset('last_7_days', 'UTC')).toEqual({
+      from: '2026-03-09',
+      to: '2026-03-15',
+    })
+  })
+
+  it('runs "this month" from the 1st to today', () => {
+    expect(resolveDatePreset('this_month', 'UTC')).toEqual({
+      from: '2026-03-01',
+      to: '2026-03-15',
+    })
+  })
+
+  it('ends "last month" the day before this one starts, whatever its length', () => {
+    // February 2026 has 28 days — derived, never assumed.
+    expect(resolveDatePreset('last_month', 'UTC')).toEqual({
+      from: '2026-02-01',
+      to: '2026-02-28',
+    })
+  })
+
+  it('treats "all" as unbounded on both sides', () => {
+    expect(resolveDatePreset('all', 'UTC')).toEqual({ from: null, to: null })
+  })
+})
+
+describe('matchDatePreset', () => {
+  it('recognises a range it produced, so a restored filter re-selects its entry', () => {
+    const range = resolveDatePreset('last_30_days', 'UTC')
+    expect(matchDatePreset(range, 'UTC')).toBe('last_30_days')
+  })
+
+  it('reads empty bounds as "all"', () => {
+    expect(matchDatePreset({ from: null, to: null }, 'UTC')).toBe('all')
+  })
+
+  it('reads a hand-picked range as custom', () => {
+    expect(matchDatePreset({ from: '2026-01-02', to: '2026-01-09' }, 'UTC')).toBe('custom')
+  })
+
+  it('reads a stale preset as custom once it no longer matches', () => {
+    // Yesterday's "last 7 days", reopened today, is a fixed range that no
+    // preset would produce now — calling it "Last 7 days" would misdescribe
+    // what the list is actually filtered to.
+    const stale = { from: '2026-03-08', to: '2026-03-14' }
+    expect(matchDatePreset(stale, 'UTC')).toBe('custom')
+  })
+
+  it('does not match a range computed in another zone', () => {
+    const sydney = resolveDatePreset('today', 'Australia/Sydney')
+    expect(matchDatePreset(sydney, 'America/Los_Angeles')).toBe('custom')
+  })
+})

package/src/lib/date-presets.ts

@@ -0,0 +1,98 @@
+import { format, startOfMonth, subDays, subMonths } from 'date-fns'
+import { toZonedTime } from 'date-fns-tz'
+
+/**
+ * Relative date ranges offered by the toolbar's quick date filter.
+ *
+ * `null` bounds mean "unbounded on that side", which is how `all` clears the
+ * filter without needing a separate signal.
+ */
+export type DatePresetKey =
+  | 'all'
+  | 'today'
+  | 'last_7_days'
+  | 'last_30_days'
+  | 'this_month'
+  | 'last_month'
+  | 'custom'
+
+/** Presets in menu order. `custom` is handled by the panel, not by this table. */
+export const DATE_PRESET_KEYS: DatePresetKey[] = [
+  'all',
+  'today',
+  'last_7_days',
+  'last_30_days',
+  'this_month',
+  'last_month',
+]
+
+export interface DateRange {
+  /** Inclusive lower bound as `yyyy-MM-dd`, or null for unbounded. */
+  from: string | null
+  /** Inclusive upper bound as `yyyy-MM-dd`, or null for unbounded. */
+  to: string | null
+}
+
+/**
+ * Resolve a preset into concrete `yyyy-MM-dd` bounds.
+ *
+ * The timezone argument is not decoration: these ranges are relative to *now*,
+ * and "today" means today where the merchant trades. Computing them in the
+ * browser's zone puts the boundary hours off for anyone checking a store from
+ * another country — and it moves depending on who is looking, which makes a
+ * shared link mean different things to two people.
+ *
+ * Bounds are whole dates because that is what the filter stores and what
+ * Ransack compares against; the day itself is the smallest unit a merchant
+ * reasons about here.
+ */
+export function resolveDatePreset(preset: DatePresetKey, timezone: string): DateRange {
+  if (preset === 'all' || preset === 'custom') return { from: null, to: null }
+
+  // "Now" shifted so that reading its *local* fields yields the store's
+  // wall-clock date. All arithmetic below then happens on the merchant's
+  // calendar, and `format` reads those same local fields back out.
+  //
+  // `formatInTimeZone` must not be used on these values: it would convert a
+  // second time, moving every bound by the offset that was already applied.
+  const now = toZonedTime(new Date(), timezone)
+  const day = (date: Date) => format(date, 'yyyy-MM-dd')
+
+  switch (preset) {
+    case 'today':
+      return { from: day(now), to: day(now) }
+    case 'last_7_days':
+      return { from: day(subDays(now, 6)), to: day(now) }
+    case 'last_30_days':
+      return { from: day(subDays(now, 29)), to: day(now) }
+    case 'this_month':
+      return { from: day(startOfMonth(now)), to: day(now) }
+    case 'last_month': {
+      const previous = subMonths(now, 1)
+      return {
+        from: day(startOfMonth(previous)),
+        // The day before this month starts — avoids month-length arithmetic.
+        to: day(subDays(startOfMonth(now), 1)),
+      }
+    }
+  }
+}
+
+/**
+ * Recognise which preset a pair of bounds came from, so a filter restored from
+ * the URL re-selects its menu entry instead of always reading as "Custom".
+ *
+ * Matching by value rather than storing the preset key keeps the filter a plain
+ * `FilterRule` — the preset is a way of writing a range, not a thing the rest
+ * of the pipeline has to know about. A range that no longer matches any preset
+ * (yesterday's "last 7 days", reopened today) correctly reads as custom.
+ */
+export function matchDatePreset(range: DateRange, timezone: string): DatePresetKey {
+  if (!range.from && !range.to) return 'all'
+  for (const key of DATE_PRESET_KEYS) {
+    if (key === 'all') continue
+    const candidate = resolveDatePreset(key, timezone)
+    if (candidate.from === range.from && candidate.to === range.to) return key
+  }
+  return 'custom'
+}

package/src/lib/delivery-form.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+
+/**
+ * One consignment's editable fields.
+ *
+ * The carrier is free text: a forwarder's own name is as valid as a
+ * registered carrier, and an empty value asks the server to detect one from
+ * the number.
+ */
+export const deliveryFormSchema = z.object({
+  tracking_number: z.string().min(1),
+  carrier: z.string(),
+})
+
+export type DeliveryFormValues = z.infer<typeof deliveryFormSchema>

package/src/lib/docs.ts

@@ -0,0 +1,32 @@
+/**
+ * Base for documentation links surfaced in the dashboard.
+ *
+ * Kept in one place so a docs restructure, a domain change or a locale prefix
+ * is a single edit rather than a sweep through every table and settings page.
+ */
+export const DOCS_BASE_URL = 'https://spreecommerce.org/docs'
+
+/**
+ * The other two destinations the account menu offers, kept here for the same
+ * reason as the docs base: one edit if a domain moves.
+ */
+export const COMMUNITY_URL = 'https://discord.spreecommerce.org'
+export const CONTACT_URL = 'https://spreecommerce.org/contact'
+
+/**
+ * Resolves a documentation path to a full URL.
+ *
+ * A bare path is taken as relative to the user guide, which is where the
+ * merchant-facing pages live; an absolute URL is returned untouched, so a
+ * plugin can point at its own documentation.
+ *
+ * @param path - `'catalogs'`, `'developer/providers/erp'`, or a full URL
+ * @returns the URL to link to
+ */
+export function docsUrl(path: string): string {
+  if (/^https?:\/\//.test(path)) return path
+
+  const trimmed = path.replace(/^\/+/, '')
+  const section = /^(user|developer)\//.test(trimmed) ? trimmed : `user/${trimmed}`
+  return `${DOCS_BASE_URL}/${section}`
+}

package/src/lib/download.ts

@@ -18,15 +18,27 @@ function resolveApiUrl(urlOrPath: string): { url: string; sameOrigin: boolean }
  * origin get the `Authorization` header and cookies, so the token can't leak
  * to a third-party host (e.g. a URL echoed back by the server). The filename
  * comes from `Content-Disposition` when present, else `fallbackName`.
+ *
+ * `extraHeaders` carries whatever else the panel's API needs to identify the
+ * request — the seller panel's `X-Spree-Seller-Id`, without which every Seller
+ * API request is refused before the action runs. Prefer
+ * `useDownloadHeaders()`, which reads them off the registered client.
  */
 export async function downloadFromApi(
   token: string | null,
   urlOrPath: string,
   fallbackName: string,
+  extraHeaders: Record<string, string> = {},
 ): Promise<void> {
   const { url, sameOrigin } = resolveApiUrl(urlOrPath)
   const headers: Record<string, string> = {}
-  if (sameOrigin && token) headers.Authorization = `Bearer ${token}`
+  if (sameOrigin && token) {
+    headers.Authorization = `Bearer ${token}`
+    // Tenant headers ride only to the API origin, for the same reason the
+    // token does — a URL echoed back by the server must not carry them
+    // anywhere else.
+    Object.assign(headers, extraHeaders)
+  }
 
   const response = await fetch(url, {
     headers,

package/src/lib/filters-to-ransack.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest'
+import { filtersToRansack } from './filters-to-ransack'
+import type { ColumnDef, FilterRule } from './table-registry'
+
+const columns: ColumnDef[] = [
+  { key: 'completed_at', label: 'Date', filterType: 'date' },
+  { key: 'status', label: 'Status', filterType: 'enum', filterOptions: [] },
+  { key: 'tags', label: 'Tags', filterType: 'tags', taggableType: 'Spree::Product' },
+  { key: 'sku', label: 'SKU', ransackAttribute: 'master_sku' },
+  {
+    key: 'companies',
+    label: 'Companies',
+    filterType: 'resource',
+    ransackAttribute: 'with_standing_for_company',
+    ransackScope: true,
+    filterResource: {
+      queryKey: 'companies',
+      search: async () => ({ data: [], meta: { count: 0, page: 1, pages: 0 } }),
+      hydrate: async () => ({ data: [], meta: { count: 0, page: 1, pages: 0 } }),
+      getOptionLabel: () => '',
+    },
+  },
+]
+
+const rule = (partial: Partial<FilterRule>): FilterRule => ({
+  id: 'r1',
+  field: 'completed_at',
+  operator: 'lteq',
+  value: '2026-08-29',
+  ...partial,
+})
+
+describe('filtersToRansack', () => {
+  it('carries a date upper bound to the end of its day', () => {
+    // The columns these target are datetimes, so a bare date casts to
+    // midnight — "up to the 29th" would drop everything that happened on the
+    // 29th, which is usually the very rows the operator is looking for.
+    expect(filtersToRansack([rule({})], columns)).toEqual({
+      completed_at_lteq: '2026-08-29 23:59:59.999999',
+    })
+  })
+
+  it('leaves a date lower bound alone, since midnight already starts the day', () => {
+    expect(filtersToRansack([rule({ operator: 'gteq', value: '2026-08-01' })], columns)).toEqual({
+      completed_at_gteq: '2026-08-01',
+    })
+  })
+
+  it('emits both ends of a range', () => {
+    const filters = [
+      rule({ id: 'a', operator: 'gteq', value: '2026-08-01' }),
+      rule({ id: 'b', operator: 'lteq', value: '2026-08-29' }),
+    ]
+    expect(filtersToRansack(filters, columns)).toEqual({
+      completed_at_gteq: '2026-08-01',
+      completed_at_lteq: '2026-08-29 23:59:59.999999',
+    })
+  })
+
+  it('does not widen a non-date column that happens to use lteq', () => {
+    const columnsWithNumber: ColumnDef[] = [
+      ...columns,
+      { key: 'total', label: 'Total', filterType: 'number' },
+    ]
+    const filters = [rule({ field: 'total', operator: 'lteq', value: '100' })]
+    expect(filtersToRansack(filters, columnsWithNumber)).toEqual({ total_lteq: '100' })
+  })
+
+  it('splits array operators into a list', () => {
+    const filters = [rule({ field: 'status', operator: 'in', value: 'active,draft' })]
+    expect(filtersToRansack(filters, columns)).toEqual({ status_in: ['active', 'draft'] })
+  })
+
+  it('drops an array operator with no values rather than filtering by nothing', () => {
+    const filters = [rule({ field: 'status', operator: 'in', value: '' })]
+    expect(filtersToRansack(filters, columns)).toEqual({})
+  })
+
+  it('targets the join column for tags', () => {
+    const filters = [rule({ field: 'tags', operator: 'in', value: 'sale' })]
+    expect(filtersToRansack(filters, columns)).toEqual({ tags_name_in: ['sale'] })
+  })
+
+  it('honours an explicit ransack alias', () => {
+    const filters = [rule({ field: 'sku', operator: 'i_cont', value: 'ABC' })]
+    expect(filtersToRansack(filters, columns)).toEqual({ master_sku_i_cont: 'ABC' })
+  })
+
+  // A scope is invoked by its bare name and takes the value as its argument,
+  // so an operator suffix would name a predicate that does not exist and
+  // silently filter nothing.
+  it('sends a scope key without an operator suffix', () => {
+    const filters = [rule({ field: 'companies', operator: 'in', value: 'comp_1,comp_2' })]
+
+    expect(filtersToRansack(filters, columns)).toEqual({
+      with_standing_for_company: ['comp_1', 'comp_2'],
+    })
+  })
+
+  // A scope takes its value as an argument and cannot express negation, so
+  // emitting the same bare key would run it as an inclusion — the exact
+  // opposite of what the merchant picked.
+  it('drops a negating operator on a scope column rather than inverting it', () => {
+    const filters = [rule({ field: 'companies', operator: 'not_in', value: 'comp_1' })]
+
+    expect(filtersToRansack(filters, columns)).toEqual({})
+  })
+
+  it('still drops an empty scope filter', () => {
+    const filters = [rule({ field: 'companies', operator: 'in', value: '' })]
+    expect(filtersToRansack(filters, columns)).toEqual({})
+  })
+})

package/src/lib/filters-to-ransack.ts

@@ -22,6 +22,8 @@ import { type ColumnDef, type FilterRule, parseFilterIds } from './table-registr
 // FilterRule[]) stays simple.
 const ARRAY_OPERATORS = new Set(['in', 'not_in'])
 
+const NEGATING_OPERATORS = new Set(['not_in', 'not_eq'])
+
 export function filtersToRansack(
   filters: FilterRule[],
   columns: ColumnDef[],
@@ -35,10 +37,29 @@ export function filtersToRansack(
     // ransack alias here when one isn't explicitly set.
     const fallback = col?.filterType === 'tags' ? 'tags_name' : filter.field
     const ransackKey = col?.ransackAttribute ?? fallback
-    const key = `${ransackKey}_${filter.operator}`
+    // A scope is invoked by its bare name and takes the value as an argument,
+    // so it cannot express negation — emitting the same key for `not_in` would
+    // run it as an inclusion.
+    if (col?.ransackScope && NEGATING_OPERATORS.has(filter.operator)) continue
+
+    const key = col?.ransackScope ? ransackKey : `${ransackKey}_${filter.operator}`
     if (ARRAY_OPERATORS.has(filter.operator)) {
       const ids = parseFilterIds(filter.value)
       if (ids.length > 0) out[key] = ids
+    } else if (col?.filterType === 'date' && filter.operator === 'lteq') {
+      // A date filter's upper bound is a whole day, but the columns it targets
+      // are datetimes: Ransack casts `2026-08-29` to midnight, so "up to the
+      // 29th" would drop everything that happened during the 29th. Carry the
+      // day's last instant instead — to the microsecond, since Rails defaults
+      // datetime columns to that precision and a bound of `23:59:59` would
+      // drop the final second of the day. The lower bound needs no such
+      // treatment: midnight is already the start of its day.
+      //
+      // Both ends are read in the server's zone, so a store trading far from
+      // it sees the same edge-of-day skew its other date filters already have.
+      // Fixing that means sending zoned bounds, which is a change to the
+      // filter wire format rather than to this conversion.
+      out[key] = `${filter.value} 23:59:59.999999`
     } else {
       out[key] = filter.value
     }

package/src/lib/form-errors.ts

@@ -1,6 +1,109 @@
+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>>,
+): 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
+
+      sentences.push(`${attributeLabel(field)} ${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:
@@ -43,11 +146,18 @@ import type { FieldValues, Path, UseFormSetError } from 'react-hook-form'
  * ```json
  * { "error": {
  *     "code": "validation_error",
- *     "message": "Code can't be blank, Name can't be blank",
- *     "details": { "code": ["can't be blank"], "name": ["can't be blank"] }
+ *     "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
@@ -61,11 +171,13 @@ export function mapSpreeErrorsToForm<TFieldValues extends FieldValues>(
 
   const { details, message } = error
 
-  // Always seed the root error with the server's top-level message. Even
-  // when details exist, the top-level message is the readable summary —
-  // and it's the only place nested/association errors will reliably show.
-  if (message) {
-    setError('root' as Path<TFieldValues>, { type: 'server', message })
+  // 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)) || message
+  if (summary) {
+    setError('root' as Path<TFieldValues>, { type: 'server', message: summary })
   }
 
   if (!details) return true
@@ -79,13 +191,13 @@ export function mapSpreeErrorsToForm<TFieldValues extends FieldValues>(
   // 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, messages] of Object.entries(details)) {
-    if (!messages?.length) continue
+  for (const [field, entries] of Object.entries(details)) {
+    if (!entries?.length) continue
     if (!isRenderableFieldKey(field)) continue
 
     setError(field as Path<TFieldValues>, {
       type: 'server',
-      message: messages.join(', '),
+      message: entries.map((entry) => resolveDetailMessage(field, entry)).join(', '),
     })
   }
 

package/src/lib/form-mappers.ts

@@ -28,3 +28,79 @@ export function emptyToUndefined(value: unknown): unknown {
   if (value === '' || value === null) return undefined
   return value
 }
+
+/**
+ * The address columns a stock location carries, in either panel's SDK shape.
+ * Structural rather than either `StockLocation` type so both the admin and
+ * seller panels can map their own rows through the helpers below.
+ */
+export interface StockLocationAddressFields {
+  company?: string | null
+  address1?: string | null
+  address2?: string | null
+  city?: string | null
+  zipcode?: string | null
+  state_code?: string | null
+  state_text?: string | null
+  country_code?: string | null
+  country_name?: string | null
+  phone?: string | null
+}
+
+/**
+ * The three shapes a stock location's address sits between. A location stores
+ * `zipcode` where an address says `postal_code`, and carries no personal name
+ * — mapping the fields explicitly keeps that difference in one place instead
+ * of leaking a cast into every call.
+ */
+export function stockLocationToAddressBlock(location: StockLocationAddressFields) {
+  return {
+    company: location.company,
+    address1: location.address1,
+    address2: location.address2,
+    city: location.city,
+    state_text: location.state_text,
+    postal_code: location.zipcode,
+    country_code: location.country_code,
+    country_name: location.country_name,
+    phone: location.phone,
+  }
+}
+
+export function stockLocationToEditableAddress(
+  location: StockLocationAddressFields & { id: string },
+) {
+  return {
+    id: location.id,
+    company: location.company,
+    address1: location.address1,
+    address2: location.address2,
+    city: location.city,
+    postal_code: location.zipcode,
+    country_code: location.country_code,
+    state_code: location.state_code,
+    phone: location.phone,
+  }
+}
+
+export function editableAddressToStockLocationParams(values: {
+  company?: string | null
+  address1?: string | null
+  address2?: string | null
+  city?: string | null
+  postal_code?: string | null
+  country_code?: string | null
+  state_code?: string | null
+  phone?: string | null
+}) {
+  return {
+    company: values.company,
+    address1: values.address1,
+    address2: values.address2,
+    city: values.city,
+    zipcode: values.postal_code,
+    country_code: values.country_code,
+    state_code: values.state_code,
+    phone: values.phone,
+  }
+}