@open-mercato/core 0.7.1-develop.7122.1.421cefe668 → 0.7.1-develop.7130.1.fef2396fd8

package/src/modules/customers/components/AddressEditor.tsx

@@ -24,7 +24,7 @@ import {
 } from '@open-mercato/ui/primitives/dialog'
 import { buildCountryOptions } from '@open-mercato/shared/lib/location/countries'
 import { buildHrefWithReturnTo } from '@open-mercato/shared/lib/navigation/returnTo'
-import type { AddressFormatStrategy } from '../utils/addressFormat'
+import { resolveTaxIdLabel, type AddressFormatStrategy } from '../utils/addressFormat'
 import { useAddressTypes } from './detail/hooks/useAddressTypes'
 
 type Translator = (key: string, fallback?: string, params?: Record<string, string | number>) => string
@@ -41,6 +41,20 @@ export type AddressEditorDraft = {
   region: string
   postalCode: string
   country: string
+  /**
+   * Contact details that belong to the ADDRESS rather than to the customer: the tax identifier it was
+   * invoiced under, and the phone a carrier calls about a delivery. Optional so every existing caller
+   * keeps compiling; callers must opt in with the matching `show*Field` props before they render.
+   */
+  taxId?: string
+  /**
+   * Which scheme the identifier belongs to, in Stripe's `{country}_{kind}` vocabulary. Chosen, not
+   * inferred: `PL1234567890` and `1234567890` are the same business written two ways, and a rule
+   * that reads the form of the value is guessing — the more schemes the vocabulary carries, the more
+   * often it guesses wrong, and a wrong type is worse than none because it names the number.
+   */
+  taxIdType?: string
+  phone?: string
   latitude?: string
   longitude?: string
   isPrimary: boolean
@@ -58,6 +72,9 @@ export type AddressEditorField =
   | 'region'
   | 'postalCode'
   | 'country'
+  | 'taxId'
+  | 'taxIdType'
+  | 'phone'
   | 'latitude'
   | 'longitude'
   | 'isPrimary'
@@ -72,8 +89,33 @@ type AddressEditorProps = {
   hidePrimaryToggle?: boolean
   showFormatHint?: boolean
   showCoordinateFields?: boolean
+  /**
+   * Render the phone. Off by default, opt-in for the same reason `showCoordinateFields` is: only a
+   * caller whose storage can hold a field should offer it.
+   */
+  showPhoneField?: boolean
+  /**
+   * Render the tax identifier and its scheme. Separate from the phone, and not for symmetry — a
+   * phone is a contact detail and a tax identifier is not, and the two stop travelling together at
+   * the next phase: `CustomerAddress` gains a `phone` column and no tax id, so the address book will
+   * offer one and not the other.
+   *
+   * Both gate the CALLER, not the field. Inside a tile that opts in, the input renders whether or not
+   * it carries a value and takes the same `disabled` as every neighbour.
+   */
+  showTaxIdField?: boolean
 }
 
+/**
+ * The schemes offered in the picker, in the order a Polish deployment meets them. The vocabulary is
+ * additive under the backward-compatibility contract, so a new scheme is a new entry here rather
+ * than a new branch in a rule that has to guess.
+ *
+ * The labels are the ones `resolveTaxIdLabel` resolves, so the picker and the marker beside the
+ * filled field always read the same.
+ */
+const TAX_ID_TYPES = ['pl_nip', 'eu_vat', 'other'] as const
+
 export function AddressEditor({
   value,
   onChange,
@@ -84,6 +126,8 @@ export function AddressEditor({
   hidePrimaryToggle = false,
   showFormatHint = true,
   showCoordinateFields = false,
+  showPhoneField = false,
+  showTaxIdField = false,
 }: AddressEditorProps) {
   const pathname = usePathname()
   const searchParams = useSearchParams()
@@ -102,6 +146,11 @@ export function AddressEditor({
     [t],
   )
 
+  const taxIdLabels = {
+    plNip: t('customers.people.detail.addresses.fields.taxId.plNip', 'Tax ID'),
+    euVat: t('customers.people.detail.addresses.fields.taxId.euVat', 'EU VAT'),
+    other: t('customers.people.detail.addresses.fields.taxId.other', 'Tax number'),
+  }
   const current: AddressEditorDraft = {
     name: value.name ?? '',
     purpose: value.purpose ?? '',
@@ -114,6 +163,9 @@ export function AddressEditor({
     region: value.region ?? '',
     postalCode: value.postalCode ?? '',
     country: value.country ?? '',
+    taxId: value.taxId ?? '',
+    taxIdType: value.taxIdType ?? '',
+    phone: value.phone ?? '',
     ...(showCoordinateFields
       ? { latitude: value.latitude ?? '', longitude: value.longitude ?? '' }
       : {}),
@@ -472,6 +524,69 @@ export function AddressEditor({
             {errors.longitude ? <p className="text-xs text-destructive">{errors.longitude}</p> : null}
           </>
         ) : null}
+        {showTaxIdField ? (
+          <>
+            <Select
+              value={current.taxIdType || undefined}
+              onValueChange={(next) => update('taxIdType', next ?? '')}
+              disabled={disabled}
+            >
+              <SelectTrigger
+                className={errors.taxIdType ? 'border-destructive' : undefined}
+                aria-label={t('customers.people.detail.addresses.fields.taxIdType', 'Tax id type')}
+                aria-invalid={errors.taxIdType ? 'true' : undefined}
+              >
+                <SelectValue
+                  placeholder={t('customers.people.detail.addresses.fields.taxIdType', 'Tax id type')}
+                />
+              </SelectTrigger>
+              <SelectContent>
+                {TAX_ID_TYPES.map((type) => (
+                  <SelectItem key={type} value={type}>
+                    {resolveTaxIdLabel(taxIdLabels, type)}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <Input
+              className={inputClass('taxId')}
+              placeholder={t('customers.people.detail.addresses.fields.taxId', 'Tax number')}
+              aria-label={t('customers.people.detail.addresses.fields.taxId', 'Tax number')}
+              rightIcon={
+                current.taxId ? (
+                  <span className="text-xs">{resolveTaxIdLabel(taxIdLabels, current.taxIdType)}</span>
+                ) : null
+              }
+              value={current.taxId ?? ''}
+              onChange={(evt) => update('taxId', evt.target.value)}
+              disabled={disabled}
+              aria-invalid={errors.taxId ? 'true' : undefined}
+            />
+            {errors.taxId ? <p className="text-xs text-destructive">{errors.taxId}</p> : null}
+          </>
+        ) : null}
+        {showPhoneField ? (
+          <>
+            <Input
+              className={inputClass('phone')}
+              placeholder={t('customers.people.detail.addresses.fields.phone', 'Phone')}
+              aria-label={t('customers.people.detail.addresses.fields.phone', 'Phone')}
+              rightIcon={
+                current.phone ? (
+                  <span className="text-xs">
+                    {t('customers.people.detail.addresses.fields.phone', 'Phone')}
+                  </span>
+                ) : null
+              }
+              inputMode="tel"
+              value={current.phone ?? ''}
+              onChange={(evt) => update('phone', evt.target.value)}
+              disabled={disabled}
+              aria-invalid={errors.phone ? 'true' : undefined}
+            />
+            {errors.phone ? <p className="text-xs text-destructive">{errors.phone}</p> : null}
+          </>
+        ) : null}
       </div>
       {!hidePrimaryToggle ? (
         <label className="inline-flex items-center gap-2 text-sm">

package/src/modules/customers/i18n/de.json

@@ -1867,11 +1867,17 @@
   "customers.people.detail.addresses.fields.line1": "Adresszeile 1",
   "customers.people.detail.addresses.fields.line2": "Adresszeile 2",
   "customers.people.detail.addresses.fields.longitude": "Längengrad",
+  "customers.people.detail.addresses.fields.phone": "Telefon",
   "customers.people.detail.addresses.fields.postalCode": "Postleitzahl",
   "customers.people.detail.addresses.fields.primary": "Als primär markieren",
   "customers.people.detail.addresses.fields.region": "Bundesland / Region",
   "customers.people.detail.addresses.fields.street": "Straße",
   "customers.people.detail.addresses.fields.streetExtra": "Weitere Adressangaben",
+  "customers.people.detail.addresses.fields.taxId": "Steuernummer",
+  "customers.people.detail.addresses.fields.taxId.euVat": "USt-IdNr.",
+  "customers.people.detail.addresses.fields.taxId.other": "Steuerliche Nummer",
+  "customers.people.detail.addresses.fields.taxId.plNip": "Steuernummer",
+  "customers.people.detail.addresses.fields.taxIdType": "Art der Steuernummer",
   "customers.people.detail.addresses.fields.type": "Adresstyp",
   "customers.people.detail.addresses.formatLoadError": "Adresskonfiguration konnte nicht geladen werden",
   "customers.people.detail.addresses.formatLoading": "Adresspräferenzen werden geladen…",

package/src/modules/customers/i18n/en.json

@@ -1867,11 +1867,17 @@
   "customers.people.detail.addresses.fields.line1": "Address line 1",
   "customers.people.detail.addresses.fields.line2": "Address line 2",
   "customers.people.detail.addresses.fields.longitude": "Longitude",
+  "customers.people.detail.addresses.fields.phone": "Phone",
   "customers.people.detail.addresses.fields.postalCode": "Postal code",
   "customers.people.detail.addresses.fields.primary": "Set as primary",
   "customers.people.detail.addresses.fields.region": "Region / State",
   "customers.people.detail.addresses.fields.street": "Street",
   "customers.people.detail.addresses.fields.streetExtra": "Additional address details",
+  "customers.people.detail.addresses.fields.taxId": "Tax number",
+  "customers.people.detail.addresses.fields.taxId.euVat": "EU VAT",
+  "customers.people.detail.addresses.fields.taxId.other": "Tax number",
+  "customers.people.detail.addresses.fields.taxId.plNip": "Tax ID",
+  "customers.people.detail.addresses.fields.taxIdType": "Tax id type",
   "customers.people.detail.addresses.fields.type": "Address type",
   "customers.people.detail.addresses.formatLoadError": "Failed to load address configuration",
   "customers.people.detail.addresses.formatLoading": "Loading address preferences…",

package/src/modules/customers/i18n/es.json

@@ -1867,11 +1867,17 @@
   "customers.people.detail.addresses.fields.line1": "Dirección (línea 1)",
   "customers.people.detail.addresses.fields.line2": "Dirección (línea 2)",
   "customers.people.detail.addresses.fields.longitude": "Longitud",
+  "customers.people.detail.addresses.fields.phone": "Teléfono",
   "customers.people.detail.addresses.fields.postalCode": "Código postal",
   "customers.people.detail.addresses.fields.primary": "Marcar como principal",
   "customers.people.detail.addresses.fields.region": "Provincia / región",
   "customers.people.detail.addresses.fields.street": "Calle",
   "customers.people.detail.addresses.fields.streetExtra": "Detalles adicionales de la dirección",
+  "customers.people.detail.addresses.fields.taxId": "Número fiscal",
+  "customers.people.detail.addresses.fields.taxId.euVat": "IVA UE",
+  "customers.people.detail.addresses.fields.taxId.other": "Número fiscal",
+  "customers.people.detail.addresses.fields.taxId.plNip": "NIF",
+  "customers.people.detail.addresses.fields.taxIdType": "Tipo de número fiscal",
   "customers.people.detail.addresses.fields.type": "Tipo de dirección",
   "customers.people.detail.addresses.formatLoadError": "No se pudo cargar la configuración de la dirección",
   "customers.people.detail.addresses.formatLoading": "Cargando preferencias de dirección…",

package/src/modules/customers/i18n/ko.json

@@ -1867,11 +1867,17 @@
   "customers.people.detail.addresses.fields.line1": "주소 1",
   "customers.people.detail.addresses.fields.line2": "주소 2",
   "customers.people.detail.addresses.fields.longitude": "경도",
+  "customers.people.detail.addresses.fields.phone": "전화번호",
   "customers.people.detail.addresses.fields.postalCode": "우편번호",
   "customers.people.detail.addresses.fields.primary": "기본 주소로 설정",
   "customers.people.detail.addresses.fields.region": "지역 / 주",
   "customers.people.detail.addresses.fields.street": "도로명",
   "customers.people.detail.addresses.fields.streetExtra": "추가 주소 정보",
+  "customers.people.detail.addresses.fields.taxId": "세금 번호",
+  "customers.people.detail.addresses.fields.taxId.euVat": "EU 부가세 번호",
+  "customers.people.detail.addresses.fields.taxId.other": "세금 번호",
+  "customers.people.detail.addresses.fields.taxId.plNip": "납세자 번호",
+  "customers.people.detail.addresses.fields.taxIdType": "세금 번호 유형",
   "customers.people.detail.addresses.fields.type": "주소 유형",
   "customers.people.detail.addresses.formatLoadError": "주소 설정을 불러오지 못했습니다",
   "customers.people.detail.addresses.formatLoading": "주소 설정을 불러오는 중…",

package/src/modules/customers/i18n/pl.json

@@ -1867,11 +1867,17 @@
   "customers.people.detail.addresses.fields.line1": "Adres (linia 1)",
   "customers.people.detail.addresses.fields.line2": "Adres (linia 2)",
   "customers.people.detail.addresses.fields.longitude": "Długość geograficzna",
+  "customers.people.detail.addresses.fields.phone": "Telefon",
   "customers.people.detail.addresses.fields.postalCode": "Kod pocztowy",
   "customers.people.detail.addresses.fields.primary": "Ustaw jako główny",
   "customers.people.detail.addresses.fields.region": "Region / województwo",
   "customers.people.detail.addresses.fields.street": "Ulica",
   "customers.people.detail.addresses.fields.streetExtra": "Dodatkowe informacje adresowe",
+  "customers.people.detail.addresses.fields.taxId": "Nr podatkowy",
+  "customers.people.detail.addresses.fields.taxId.euVat": "VAT UE",
+  "customers.people.detail.addresses.fields.taxId.other": "Nr podatkowy",
+  "customers.people.detail.addresses.fields.taxId.plNip": "NIP",
+  "customers.people.detail.addresses.fields.taxIdType": "Typ numeru",
   "customers.people.detail.addresses.fields.type": "Typ adresu",
   "customers.people.detail.addresses.formatLoadError": "Nie udało się wczytać konfiguracji adresów",
   "customers.people.detail.addresses.formatLoading": "Ładowanie preferencji adresowych…",

package/src/modules/customers/utils/addressFormat.tsx

@@ -13,6 +13,34 @@ export type AddressValue = {
   postalCode?: string | null
   country?: string | null
   companyName?: string | null
+  /**
+   * Contact details that belong to the ADDRESS rather than to the customer: who to call about this
+   * delivery, and the tax identifier this invoice address was billed under. They remain available to
+   * address editors and snapshot payloads, but are deliberately excluded from `formatAddressLines`
+   * and `AddressView`, whose existing contract remains postal-only.
+   *
+   * `taxIdType` interprets the value in Stripe's `{country}_{kind}` vocabulary (`pl_nip`, `eu_vat`,
+   * `other`, widened additively): `1234567890` and `PL1234567890` are the same business, and only the
+   * type tells a domestic identifier from an EU VAT number. It is metadata about `taxId`, never a
+   * displayed field of its own.
+   */
+  phone?: string | null
+  taxId?: string | null
+  taxIdType?: string | null
+}
+
+/**
+ * Tax-id labels keyed by `taxIdType`, for a caller that wants the identifier named correctly rather
+ * than generically.
+ *
+ * The stored scheme is chosen explicitly rather than inferred from the identifier. `other` also
+ * covers an address written before `taxIdType` existed. An unrecognised type takes the `other` route
+ * instead of guessing a domestic scheme.
+ */
+export type TaxIdLabelByType = {
+  plNip: string
+  euVat: string
+  other: string
 }
 
 export type AddressJsonShape = {
@@ -100,6 +128,31 @@ export function formatAddressString(address: AddressValue, format: AddressFormat
   return formatAddressLines(address, format).filter(Boolean).join(separator)
 }
 
+/**
+ * Which member of a label map names which scheme. Private, and deliberately not exhaustive: an
+ * unrecognised type resolves to `other`, so the vocabulary can widen without every caller being
+ * updated in the same release.
+ */
+const TAX_ID_LABEL_KEY_BY_TYPE: Record<string, keyof TaxIdLabelByType> = {
+  pl_nip: 'plNip',
+  eu_vat: 'euVat',
+}
+
+/**
+ * The label a tax identifier should carry, given its type. Exported because the editor renders the
+ * same identifier as an input and must name it the same way this formatter does — two copies of the
+ * mapping is exactly how a foreign number ends up under a domestic scheme's name.
+ */
+export function resolveTaxIdLabel(
+  label: string | TaxIdLabelByType | undefined,
+  taxIdType: string | null | undefined,
+): string | undefined {
+  if (!label) return undefined
+  if (typeof label === 'string') return label
+  const key = TAX_ID_LABEL_KEY_BY_TYPE[typeof taxIdType === 'string' ? taxIdType : ''] ?? 'other'
+  return label[key]
+}
+
 type AddressViewProps = {
   address: AddressValue
   format: AddressFormatStrategy
@@ -107,7 +160,12 @@ type AddressViewProps = {
   lineClassName?: string
 }
 
-export function AddressView({ address, format, className, lineClassName }: AddressViewProps): React.ReactElement | null {
+export function AddressView({
+  address,
+  format,
+  className,
+  lineClassName,
+}: AddressViewProps): React.ReactElement | null {
   const lines = formatAddressLines(address, format)
   if (!lines.length) return null
   return (

package/src/modules/sales/components/documents/AddressesSection.tsx

@@ -1,5 +1,3 @@
-// @ts-nocheck
-
 "use client"
 
 import * as React from 'react'
@@ -72,17 +70,47 @@ const emptyDraft: AddressEditorDraft = {
   region: '',
   postalCode: '',
   country: '',
+  taxId: '',
+  taxIdType: '',
+  phone: '',
   isPrimary: false,
 }
 
 const EDITABLE_SNAPSHOT_KEYS = new Set(Object.keys(emptyDraft))
 
+/**
+ * The fields the editor owns, typed, plus whatever else the caller's snapshot carried.
+ *
+ * The index signature is what lets an integration's extra keys — anything a future
+ * integration writes — survive the merge-back below, while the named fields stay `string` for callers
+ * that read them. `taxId` and `phone` are NOT among them any more: the editor renders both, so they
+ * are assigned from the draft like every other field. Reading
+ * `normalized.city` off a bare `Record<string, unknown>` yields `unknown`, which is what forced the
+ * `@ts-nocheck` on this file.
+ */
+type NormalizedAddressDraft = {
+  name?: string
+  purpose?: string
+  companyName?: string
+  addressLine1?: string
+  addressLine2?: string
+  buildingNumber?: string
+  flatNumber?: string
+  city?: string
+  region?: string
+  postalCode?: string
+  country?: string
+  taxId?: string
+  phone?: string
+  isPrimary?: boolean
+} & Record<string, unknown>
+
 function normalizeAddressDraft(
   draft?: AddressEditorDraft | null,
   previous?: Record<string, unknown> | null,
-): Record<string, unknown> | null {
+): NormalizedAddressDraft | null {
   if (!draft) return null
-  const normalized: Record<string, unknown> = {}
+  const normalized: NormalizedAddressDraft = {}
   let hasEditableContent = false
   const assign = (key: keyof AddressEditorDraft, target: string) => {
     const value = draft[key]
@@ -103,6 +131,9 @@ function normalizeAddressDraft(
   assign('region', 'region')
   assign('postalCode', 'postalCode')
   assign('country', 'country')
+  assign('taxId', 'taxId')
+  assign('taxIdType', 'taxIdType')
+  assign('phone', 'phone')
   assign('isPrimary', 'isPrimary')
   if (!hasEditableContent) return null
   if (previous) {
@@ -129,6 +160,9 @@ function draftFromSnapshot(snapshot?: Record<string, unknown> | null): AddressEd
     region: typeof record.region === 'string' ? record.region : '',
     postalCode: typeof record.postalCode === 'string' ? record.postalCode : '',
     country: typeof record.country === 'string' ? record.country : '',
+    taxId: typeof record.taxId === 'string' ? record.taxId : '',
+    taxIdType: typeof record.taxIdType === 'string' ? record.taxIdType : '',
+    phone: typeof record.phone === 'string' ? record.phone : '',
     isPrimary: record.isPrimary === true,
   }
 }
@@ -370,7 +404,10 @@ export function SalesDocumentAddressesSection({
               companyName: value.companyName ?? null,
             }
           })
-          .filter((entry): entry is DocumentAddressAssignment => entry !== null)
+          // Narrow to non-null only. Asserting `DocumentAddressAssignment` here was wrong: its
+          // optional fields (`name?`, `purpose?`, …) admit `undefined`, which the mapped literal's
+          // `string | null` does not, so the predicate was not assignable to what it filtered.
+          .filter((entry): entry is NonNullable<typeof entry> => entry !== null)
         setDocumentAddresses(mapped)
       } else {
         setDocumentAddresses([])
@@ -1093,9 +1130,12 @@ export function SalesDocumentAddressesSection({
               <AddressEditor
                 value={shippingDraft}
                 format={addressFormat}
+                showPhoneField
+                showTaxIdField
                 t={t as Translator}
                 onChange={(next) => setShippingDraft(next)}
                 hidePrimaryToggle
+                disabled={locked}
               />
               <SwitchField
                 label={t('sales.documents.form.address.saveToCustomer', 'Save this address to the customer')}
@@ -1160,9 +1200,12 @@ export function SalesDocumentAddressesSection({
                   <AddressEditor
                     value={billingDraft}
                     format={addressFormat}
+                    showPhoneField
+                    showTaxIdField
                     t={t as Translator}
                     onChange={(next) => setBillingDraft(next)}
                     hidePrimaryToggle
+                    disabled={locked}
                   />
                   <SwitchField
                     label={t('sales.documents.form.address.saveToCustomer', 'Save this address to the customer')}

package/src/modules/sales/components/documents/SalesDocumentForm.tsx

@@ -60,6 +60,7 @@ import { AddressEditor, type AddressEditorDraft } from '@open-mercato/core/modul
 import { useSalesChannelsEnabled } from '../useSalesChannelsEnabled'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import { SalesOrderDraftLines, createSalesOrderLineDraft, type SalesOrderLineDraft } from './SalesOrderDraftLines'
+import { normalizeAddressDraft } from './normalizeAddressDraft'
 
 const logger = createLogger('sales')
 
@@ -435,29 +436,6 @@ function parseCustomerOptions(items: unknown[], kind: 'person' | 'company'): Cus
   return parsed
 }
 
-function normalizeAddressDraft(draft?: AddressDraft | null): Record<string, unknown> | null {
-  if (!draft) return null
-  const normalized: Record<string, unknown> = {}
-  const assign = (key: keyof AddressDraft, target: string) => {
-    const value = draft[key]
-    if (typeof value === 'string' && value.trim().length) normalized[target] = value.trim()
-    if (typeof value === 'boolean') normalized[target] = value
-  }
-  assign('name', 'name')
-  assign('purpose', 'purpose')
-  assign('companyName', 'companyName')
-  assign('addressLine1', 'addressLine1')
-  assign('addressLine2', 'addressLine2')
-  assign('buildingNumber', 'buildingNumber')
-  assign('flatNumber', 'flatNumber')
-  assign('city', 'city')
-  assign('region', 'region')
-  assign('postalCode', 'postalCode')
-  assign('country', 'country')
-  assign('isPrimary', 'isPrimary')
-  return Object.keys(normalized).length ? normalized : null
-}
-
 type DocumentNumberFieldProps = CrudCustomFieldRenderProps & { t: Translator }
 
 type BillingAddressSectionFieldProps = CrudCustomFieldRenderProps & {
@@ -655,6 +633,8 @@ function BillingAddressSectionField({ values, setFormValue, t, addressesLoading,
                 t={t}
                 onChange={(next) => updateValue('billingAddressDraft', next)}
                 hidePrimaryToggle
+                showPhoneField
+                showTaxIdField
               />
               <SwitchField
                 containerClassName="col-span-2"
@@ -1267,6 +1247,8 @@ export function SalesDocumentForm({ onCreated, isSubmitting = false, initialKind
                   t={t}
                   onChange={(next) => updateValue('shippingAddressDraft', next)}
                   hidePrimaryToggle
+                  showPhoneField
+                  showTaxIdField
                 />
                 <SwitchField
                   containerClassName="col-span-2"

package/src/modules/sales/components/documents/normalizeAddressDraft.ts

@@ -0,0 +1,29 @@
+import type { AddressEditorDraft } from '@open-mercato/core/modules/customers/components/AddressEditor'
+
+export function normalizeAddressDraft(
+  draft?: AddressEditorDraft | null,
+): Record<string, unknown> | null {
+  if (!draft) return null
+  const normalized: Record<string, unknown> = {}
+  const assign = (key: keyof AddressEditorDraft, target: string) => {
+    const value = draft[key]
+    if (typeof value === 'string' && value.trim().length) normalized[target] = value.trim()
+    if (typeof value === 'boolean') normalized[target] = value
+  }
+  assign('name', 'name')
+  assign('purpose', 'purpose')
+  assign('companyName', 'companyName')
+  assign('addressLine1', 'addressLine1')
+  assign('addressLine2', 'addressLine2')
+  assign('buildingNumber', 'buildingNumber')
+  assign('flatNumber', 'flatNumber')
+  assign('city', 'city')
+  assign('region', 'region')
+  assign('postalCode', 'postalCode')
+  assign('country', 'country')
+  assign('taxId', 'taxId')
+  assign('taxIdType', 'taxIdType')
+  assign('phone', 'phone')
+  assign('isPrimary', 'isPrimary')
+  return Object.keys(normalized).length ? normalized : null
+}