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

package/src/products/product-form-mapping.ts

@@ -0,0 +1,212 @@
+import { i18n } from '../lib/i18n'
+import { normalizeQuantityRule } from './normalize-quantity'
+import type { MediaType, ProductFormValues, VariantFormValues } from './product-schema'
+import type { PanelMedia, PanelProduct, PanelVariant } from './product-types'
+
+/**
+ * Between the API's shape and the form's.
+ *
+ * Shared by both panels for the same reason the cards are: the form is one
+ * form, so what fills it and what it sends have to agree, and two copies of
+ * this mapping would be two ways to disagree.
+ */
+
+export function variantToFormValues(variant: PanelVariant, position: number): VariantFormValues {
+  return {
+    id: variant.id,
+    sku: variant.sku ?? null,
+    barcode: variant.barcode ?? null,
+    position,
+    // Derive {name, value} pairs from option_values. The serializer carries
+    // option_type_name on each OptionValue, so no extra expand is needed.
+    options: (variant.option_values ?? []).map((ov) => ({
+      name: ov.option_type_name,
+      value: ov.name,
+    })),
+    weight: variant.weight ?? null,
+    height: variant.height ?? null,
+    width: variant.width ?? null,
+    depth: variant.depth ?? null,
+    weight_unit: variant.weight_unit ?? null,
+    dimensions_unit: variant.dimensions_unit ?? null,
+    hs_code: variant.hs_code ?? null,
+    country_of_origin: variant.country_of_origin ?? null,
+    customs_description: variant.customs_description ?? null,
+    minimum_order_quantity: variant.minimum_order_quantity?.toString() ?? null,
+    order_multiple: variant.order_multiple?.toString() ?? null,
+    purchase_unit: variant.purchase_unit ?? null,
+    units_per_carton: variant.units_per_carton?.toString() ?? null,
+    cartons_per_pallet: variant.cartons_per_pallet?.toString() ?? null,
+    carton_weight: variant.carton_weight == null ? null : Number(variant.carton_weight),
+    carton_package_type_id: variant.carton_package_type_id ?? null,
+    track_inventory: variant.track_inventory,
+    preorderable: variant.preorderable ?? false,
+    preorder_ships_at: variant.preorder_ships_at ?? null,
+    backorder_limit: variant.backorder_limit ?? null,
+    tax_category_id: variant.tax_category_id ?? null,
+    prices: (variant.prices ?? [])
+      .filter((p) => p.currency != null)
+      .map((p) => ({
+        currency: p.currency as string,
+        // Keep amounts as the canonical decimal strings the API returns.
+        // The bulk price editor displays them with the locale's decimal
+        // separator and ships the raw user input unchanged on submit;
+        // `Spree::LocalizedNumber.parse` handles locale-aware parsing.
+        amount: p.amount != null ? String(p.amount) : '',
+        compare_at_amount: p.compare_at_amount != null ? String(p.compare_at_amount) : null,
+      })),
+    stock_levels: (variant.stock_levels ?? []).map((si) => ({
+      id: si.id,
+      stock_location_id: si.stock_location_id ?? si.stock_location?.id ?? '',
+      stock_location_name:
+        si.stock_location?.name ?? i18n.t('admin.products.inventory.unknown_location'),
+      count_on_hand: si.count_on_hand,
+      backorderable: si.backorderable,
+    })),
+  }
+}
+
+// One mapping for both hydration paths (the form reset and the media-only
+// late paint) so a new media field can't reach one and miss the other.
+// Takes the generated SDK type rather than a hand-listed shape, so a field
+// added to the serializer can't quietly go missing here.
+export function mediaToFormValues(media: PanelMedia, index: number) {
+  return {
+    id: media.id,
+    alt: media.alt ?? null,
+    position: media.position ?? index + 1,
+    variant_ids: media.variant_ids ?? [],
+    media_type: (media.media_type ?? 'image') as MediaType,
+    external_video_url: media.external_video_url ?? null,
+    focal_point_x: media.focal_point_x ?? null,
+    focal_point_y: media.focal_point_y ?? null,
+    // Video rows have no image of their own, so the poster is the preview.
+    previewUrl:
+      media.small_url ?? media.mini_url ?? media.poster_url ?? media.original_url ?? undefined,
+    // Only the square renditions: the focal point is picked against the
+    // rendered box, and original_url is uncropped, so mixing them in would
+    // move the point the merchant set.
+    fullPreviewUrl: media.large_url ?? media.xlarge_url ?? media.poster_url ?? null,
+    posterUrl: media.poster_url,
+    // The file itself, so an uploaded video can actually play. Every sized URL
+    // on a video row resolves to its poster, so none of them work here.
+    videoUrl: media.video_url,
+    downloadUrl: media.download_url,
+  }
+}
+
+export function productToFormValues(
+  product: PanelProduct,
+  // Optional media list — passed in from useProductMedia (which is a separate
+  // query). When provided we hydrate form.media here so the form.reset cycle
+  // captures it atomically instead of via a follow-up setValue that races
+  // with the merchant's unsaved edits.
+  media?: PanelMedia[],
+): ProductFormValues {
+  const hasVariants = (product.variant_count ?? 0) > 0
+  const variantSource = hasVariants
+    ? (product.variants ?? [])
+    : product.default_variant
+      ? [product.default_variant]
+      : []
+
+  return {
+    name: product.name,
+    // Hydrate the Tiptap editor from the HTML field, not `description` — the
+    // serializer squishes that one to tag-stripped plain text, which would
+    // collapse paragraphs/line breaks on every reload. Writes send the editor's
+    // HTML back under the plain `description` param.
+    description: product.description_html ?? '',
+    status: (product.status as ProductFormValues['status']) ?? 'draft',
+    category_ids: product.categories?.map((category) => category.id) ?? product.category_ids ?? [],
+    // Manual membership only — this field is what the picker edits, and the
+    // API preserves automatic membership regardless of what it sends. Hydrating
+    // automatic collections here would render chips a merchant can remove to
+    // no effect.
+    collection_ids:
+      product.collections?.filter((collection) => !collection.automatic).map((c) => c.id) ??
+      product.collection_ids ??
+      [],
+    tags: product.tags ?? [],
+    tax_category_id: product.tax_category_id ?? null,
+    product_type_id: product.product_type_id ?? null,
+    delivery_profile_id: product.delivery_profile_id ?? null,
+    meta_title: product.meta_title ?? '',
+    meta_description: product.meta_description ?? '',
+    slug: product.slug ?? '',
+    variants: variantSource.map((v, i) => variantToFormValues(v, i)),
+    custom_fields:
+      product.custom_fields?.map((cf) => ({
+        id: cf.id,
+        custom_field_definition_id: cf.custom_field_definition_id,
+        value: cf.value,
+      })) ?? [],
+    media: media?.map(mediaToFormValues) ?? [],
+    product_publications: (product.product_publications ?? []).map((l) => ({
+      id: l.id,
+      channel_id: l.channel_id,
+      published_at: l.published_at ?? null,
+      unpublished_at: l.unpublished_at ?? null,
+    })),
+  }
+}
+
+// Strip UI-only fields (stock_location_name) and undefined entries so the
+// PATCH body matches the Admin API VariantUpdateParams shape exactly. The
+// Spree::Product#variants= setter reconciles by id, creates new entries,
+// and removes any persisted variant not present in the array — see
+// docs/plans/6.0-remove-master-variant.md.
+//
+// `index` is the variant's array position; we ship `index + 1` so
+// `acts_as_list` persists the 1-indexed order. Form state stays 0-indexed
+// (matches the React array), the API quirk lives only at this boundary.
+export function variantToWirePayload(v: VariantFormValues, index: number) {
+  // DB columns `sku` and `weight` are NOT NULL with defaults ("", 0.0).
+  // The other scalar fields (barcode, dimensions, weight_unit,
+  // dimensions_unit, tax_category_id) ARE nullable — those we always send
+  // even when null so the merchant can clear them. NOT-NULL fields fall
+  // back to their schema defaults when blank.
+  const payload: Record<string, unknown> = {
+    position: index + 1,
+    options: v.options,
+    sku: v.sku ?? '',
+    weight: v.weight ?? 0,
+    barcode: v.barcode ?? null,
+    height: v.height ?? null,
+    width: v.width ?? null,
+    depth: v.depth ?? null,
+    weight_unit: v.weight_unit ?? null,
+    dimensions_unit: v.dimensions_unit ?? null,
+    tax_category_id: v.tax_category_id ?? null,
+    hs_code: v.hs_code ?? null,
+    country_of_origin: v.country_of_origin ?? null,
+    customs_description: v.customs_description ?? null,
+    minimum_order_quantity: normalizeQuantityRule(v.minimum_order_quantity),
+    order_multiple: normalizeQuantityRule(v.order_multiple),
+    purchase_unit: v.purchase_unit ?? null,
+    units_per_carton: normalizeQuantityRule(v.units_per_carton),
+    cartons_per_pallet: normalizeQuantityRule(v.cartons_per_pallet),
+    carton_weight: v.carton_weight ?? null,
+    carton_package_type_id: v.carton_package_type_id ?? null,
+  }
+  if (v.id) payload.id = v.id
+  if (v.track_inventory != null) payload.track_inventory = v.track_inventory
+  if (v.preorderable != null) payload.preorderable = v.preorderable
+  if (v.preorder_ships_at !== undefined) payload.preorder_ships_at = v.preorder_ships_at
+  if (v.backorder_limit !== undefined) payload.backorder_limit = v.backorder_limit
+  // Always send `prices` when the form tracks it — including `[]`. The
+  // backend's `Spree::Variant#prices=` treats an empty array as "clear all
+  // base prices"; omitting it would otherwise leave the old amounts in
+  // place when the merchant clears the last currency from the matrix.
+  //
+  // Amounts in form state are already canonical `"1234.56"` — the price editor
+  // normalizes the merchant's localized input on commit (see
+  // `ProductBulkPriceEditor#handleChange`), and untouched values hydrate from
+  // the canonical API. So no normalization here — re-normalizing a canonical
+  // value under a comma-decimal locale would mangle it (`34.56` → `3456`).
+  if (v.prices != null) payload.prices = v.prices
+  if (v.stock_levels?.length) {
+    payload.stock_levels = v.stock_levels.map(({ stock_location_name, ...rest }) => rest)
+  }
+  return payload
+}

package/src/products/product-schema.ts

@@ -0,0 +1,318 @@
+import { requiredMessage } from '@spree/dashboard-ui'
+import i18n from 'i18next'
+import { z } from 'zod/v4'
+import { normalizeQuantityRule } from './normalize-quantity'
+import { isSupportedVideoUrl } from './video-url'
+
+/**
+ * A purchasing rule as typed. Blank means the rule is unset — a valid
+ * answer — so only a non-blank entry that normalizes away is an error.
+ */
+const quantityRuleField = z
+  .string()
+  .nullable()
+  .optional()
+  .refine((value) => !value?.trim() || normalizeQuantityRule(value) !== null, {
+    error: () => i18n.t('admin.fields.variant.quantity_rule_invalid'),
+  })
+
+export const stockLevelFormSchema = z.object({
+  id: z.string().optional(),
+  stock_location_id: z.string(),
+  stock_location_name: z.string().optional(),
+  count_on_hand: z.coerce.number().int(),
+  backorderable: z.boolean(),
+})
+
+export type StockLevelFormValues = z.infer<typeof stockLevelFormSchema>
+
+export const variantOptionPairSchema = z.object({
+  name: z.string().min(1),
+  value: z.string().min(1),
+})
+
+export type VariantOptionPair = z.infer<typeof variantOptionPairSchema>
+
+// Form-side prices use raw STRING amounts (the merchant's typed input).
+// The backend's `Spree::LocalizedNumber.parse` handles locale-aware parsing
+// (comma decimals, grouped digits, etc.), so the frontend ships exactly what
+// the merchant typed — no `Number(...)` coercion that mangles `"1.234,56"`
+// into `NaN` and silently drops the price.
+export const variantPriceFormSchema = z.object({
+  currency: z.string(),
+  amount: z.string(),
+  compare_at_amount: z.string().nullable().optional(),
+})
+
+export type VariantPriceFormValues = z.infer<typeof variantPriceFormSchema>
+
+export const variantFormSchema = z.object({
+  // Present for persisted variants. Omit for newly-generated rows so the
+  // API can create them. Spree::Product#variants= reconciles by id.
+  id: z.string().optional(),
+  sku: z.string().nullable().optional(),
+  barcode: z.string().nullable().optional(),
+  position: z.number().int().nonnegative(),
+  options: z.array(variantOptionPairSchema),
+  weight: z.coerce.number().nullable().optional(),
+  height: z.coerce.number().nullable().optional(),
+  width: z.coerce.number().nullable().optional(),
+  depth: z.coerce.number().nullable().optional(),
+  weight_unit: z.string().nullable().optional(),
+  dimensions_unit: z.string().nullable().optional(),
+  hs_code: z.string().nullable().optional(),
+  country_of_origin: z.string().nullable().optional(),
+  customs_description: z.string().nullable().optional(),
+  // Held as strings so an unusable entry can be reported rather than
+  // silently coerced away: normalizing `0` straight to null would clear the
+  // rule while the merchant believes they set one.
+  minimum_order_quantity: quantityRuleField,
+  order_multiple: quantityRuleField,
+  purchase_unit: z.string().nullable().optional(),
+  units_per_carton: quantityRuleField,
+  cartons_per_pallet: quantityRuleField,
+  // The server refuses a carton that weighs nothing, and a 422 on a nested
+  // variant lands on a banner naming no variant — so it is caught on the field.
+  carton_weight: z.coerce
+    .number()
+    .positive({ error: () => i18n.t('admin.fields.variant.carton_weight_invalid') })
+    .nullable()
+    .optional(),
+  carton_package_type_id: z.string().nullable().optional(),
+  track_inventory: z.boolean().optional(),
+  preorderable: z.boolean().optional(),
+  preorder_ships_at: z.string().nullable().optional(),
+  backorder_limit: z.coerce.number().int().nonnegative().nullable().optional(),
+  tax_category_id: z.string().nullable().optional(),
+  prices: z.array(variantPriceFormSchema).optional(),
+  stock_levels: z.array(stockLevelFormSchema).optional(),
+})
+
+export type VariantFormValues = z.infer<typeof variantFormSchema>
+
+export const customFieldFormSchema = z.object({
+  // Prefixed id of an existing custom-field value. Present when hydrating a
+  // persisted record so edits patch the existing row rather than insert.
+  id: z.string().optional(),
+  custom_field_definition_id: z.string(),
+  value: z.unknown(),
+})
+
+export type CustomFieldFormValues = z.infer<typeof customFieldFormSchema>
+
+// Media in form state. Persisted entries carry an `id`; pre-save entries carry
+// a `signed_id` (from a completed ActiveStorage direct upload) or a
+// `source_media_id` (a file picked from the library). All can hold edits to
+// alt, position, and variant_ids that the parent product PATCH/POST ships
+// inline. previewUrl + uploadId are UI-only; stripped at submit.
+export const MEDIA_TYPES = ['image', 'video', 'external_video'] as const
+
+export type MediaType = (typeof MEDIA_TYPES)[number]
+
+export const mediaFormSchema = z
+  .object({
+    id: z.string().optional(),
+    signed_id: z.string().optional(),
+    // A file picked from the library. The save places a copy sharing the
+    // source's file rather than uploading a second one.
+    source_media_id: z.string().optional(),
+    alt: z.string().nullable().optional(),
+    position: z.number().int().nonnegative().optional(),
+    variant_ids: z.array(z.string()).optional(),
+    media_type: z.enum(MEDIA_TYPES).optional(),
+    external_video_url: z.string().nullable().optional(),
+    // A video's still frame. Sent as a signed id like the media file itself;
+    // `posterUrl` is the UI-only preview and never reaches the API.
+    poster_signed_id: z.string().optional(),
+    posterUrl: z.string().nullable().optional(),
+    // Playback source for an uploaded video. UI-only: a blob URL before save,
+    // the served file after. Never sent back.
+    videoUrl: z.string().nullable().optional(),
+    focal_point_x: z.number().min(0).max(1).nullable().optional(),
+    focal_point_y: z.number().min(0).max(1).nullable().optional(),
+    // UI-only — strip at submit.
+    previewUrl: z.string().optional(),
+    // Larger rendition for the edit sheet; previewUrl is grid-sized and
+    // visibly pixelates when blown up. Absent before save, where the blob URL
+    // in previewUrl is full resolution anyway.
+    fullPreviewUrl: z.string().nullable().optional(),
+    // Server URL for downloading the original; absent until the row is saved.
+    downloadUrl: z.string().nullable().optional(),
+    uploadId: z.string().optional(),
+  })
+  // The server rejects a link it can't embed, and that failure aborts the whole
+  // product save. Catch it here so the merchant sees it on the field instead.
+  .refine(
+    (media) =>
+      media.media_type !== 'external_video' || isSupportedVideoUrl(media.external_video_url),
+    { message: 'unsupported_video_provider', path: ['external_video_url'] },
+  )
+
+export type MediaFormValues = z.infer<typeof mediaFormSchema>
+
+// A downloadable file staged on the new-product form. Create-time only: each
+// entry is an upload (signed_id) buffered until the product POST. UI-only
+// fields (filename, byteSize, uploadId) are stripped at submit.
+export const digitalFileFormSchema = z.object({
+  signed_id: z.string(),
+  filename: z.string().nullable().optional(),
+  byteSize: z.number().nullable().optional(),
+  uploadId: z.string().optional(),
+})
+
+export type DigitalFileFormValues = z.infer<typeof digitalFileFormSchema>
+
+export const productPublicationFormSchema = z.object({
+  id: z.string().optional(),
+  channel_id: z.string(),
+  published_at: z.string().nullable().optional(),
+  unpublished_at: z.string().nullable().optional(),
+})
+
+export type ProductPublicationFormValues = z.infer<typeof productPublicationFormSchema>
+
+export const productFormSchema = z.object({
+  // General
+  name: z.string().min(1, { error: requiredMessage('name') }),
+  description: z.string().optional(),
+
+  // Status
+  // Every status the API may answer, not just the ones a form sets. A
+  // marketplace product also comes back `proposed` or `rejected`, and a schema
+  // that rejects those makes the whole form unsavable rather than flagging a
+  // field (docs/plans/6.0-seller-product-submission.md).
+  status: z.enum(['draft', 'active', 'archived', 'proposed', 'rejected']).optional(),
+
+  // Categorization
+  category_ids: z.array(z.string()).optional(),
+  collection_ids: z.array(z.string()).optional(),
+  tags: z.array(z.string()).optional(),
+
+  // Tax
+  tax_category_id: z.string().nullable().optional(),
+
+  // Product type — a creation-time template for the product's associations
+  product_type_id: z.string().nullable().optional(),
+
+  // Fulfillment profile — decides which zones and delivery methods reach this
+  // product; null falls back to the store default profile.
+  delivery_profile_id: z.string().nullable().optional(),
+
+  // SEO
+  meta_title: z.string().optional(),
+  meta_description: z.string().optional(),
+  slug: z.string().optional(),
+
+  // Variants — the single source of truth for purchasable attributes.
+  // Spree::Product#variants= matches by id, creates new entries, and
+  // removes any persisted variant not present in the array. See
+  // docs/plans/6.0-remove-master-variant.md for the wire contract.
+  variants: z.array(variantFormSchema).optional(),
+
+  // Inline custom field values, keyed by definition id (upserted server-side
+  // via Spree::HasCustomFields#custom_fields=). Partial updates: omitting a
+  // definition leaves its value untouched.
+  custom_fields: z.array(customFieldFormSchema).optional(),
+
+  // Media. On the new product page this starts empty and accumulates
+  // pre-save uploads (with signed_id). On the edit page it's hydrated from
+  // the persisted assets (with id) so edits to alt/position/variant_ids and
+  // new uploads ride the same product PATCH.
+  media: z.array(mediaFormSchema).optional(),
+
+  // Downloadable files, staged pre-save on the new product page and shipped in
+  // the product POST. Edit uses the live API-driven card instead, so this stays
+  // empty there.
+  digital_assets: z.array(digitalFileFormSchema).optional(),
+
+  product_publications: z.array(productPublicationFormSchema).optional(),
+})
+
+export type ProductFormValues = z.infer<typeof productFormSchema>
+
+// Defaults for the "new product" page. Starts with a single placeholder
+// variant (no options, empty stock_levels/prices) so the variants matrix
+// renders a "Default variant" row the merchant can edit pre-save. On submit
+// the page strips this row if it carries no meaningful data, letting
+// Spree::Product#variants= auto-create the default variant server-side.
+export function newProductFormDefaults(): ProductFormValues {
+  return {
+    name: '',
+    description: '',
+    status: 'draft',
+    category_ids: [],
+    collection_ids: [],
+    tags: [],
+    tax_category_id: null,
+    product_type_id: null,
+    delivery_profile_id: null,
+    meta_title: '',
+    meta_description: '',
+    slug: '',
+    variants: [
+      {
+        sku: null,
+        barcode: null,
+        position: 0,
+        options: [],
+        weight: null,
+        height: null,
+        width: null,
+        depth: null,
+        weight_unit: null,
+        dimensions_unit: null,
+        track_inventory: true,
+        tax_category_id: null,
+        prices: [],
+        stock_levels: [],
+      },
+    ],
+    custom_fields: [],
+    media: [],
+    digital_assets: [],
+    product_publications: [],
+  }
+}
+
+// Returns true if the given variant is essentially the empty default —
+// no merchant-entered data on any variant-only field. Used by the create
+// page to strip the placeholder variant so the backend auto-creates the
+// canonical default variant.
+//
+// Stays in sync with `hasVariantOnlyData` in new.tsx — any field that
+// makes the variant "meaningful" enough to ship inline must also count
+// as "not a placeholder" here. Otherwise simple-product creates would
+// filter the variant out before ever consulting hasVariantOnlyData.
+export function isPlaceholderDefaultVariant(v: VariantFormValues): boolean {
+  return (
+    !v.id &&
+    !v.sku &&
+    !v.barcode &&
+    v.options.length === 0 &&
+    (v.prices ?? []).length === 0 &&
+    (v.stock_levels ?? []).length === 0 &&
+    v.weight == null &&
+    v.height == null &&
+    v.width == null &&
+    v.depth == null &&
+    v.weight_unit == null &&
+    v.dimensions_unit == null &&
+    v.tax_category_id == null &&
+    !v.hs_code &&
+    !v.country_of_origin &&
+    !v.customs_description &&
+    !v.minimum_order_quantity &&
+    !v.order_multiple &&
+    v.purchase_unit == null &&
+    !v.units_per_carton &&
+    !v.cartons_per_pallet &&
+    v.carton_weight == null &&
+    v.carton_package_type_id == null &&
+    v.preorderable !== true &&
+    v.preorder_ships_at == null &&
+    v.backorder_limit == null &&
+    // `track_inventory` defaults to `true` in `newProductFormDefaults`. Only
+    // count an explicit `false` (merchant toggled it off) as non-default.
+    v.track_inventory !== false
+  )
+}

package/src/products/product-types.ts

@@ -0,0 +1,130 @@
+/**
+ * What the shared product form reads off a product, its variants and its
+ * media.
+ *
+ * Structural rather than either SDK's generated type, for the same reason
+ * `PanelStockLocation` is: the operator's Admin API and a seller's Seller API
+ * serialize the same records, and the cards only ever touch the fields both
+ * carry. Typing these against `@spree/admin-sdk` would make the form
+ * unusable in a panel that holds no admin credential.
+ *
+ * Everything a panel may omit is optional, so a card can hide what it was not
+ * given rather than render a blank.
+ */
+
+export interface PanelMedia {
+  id: string
+  media_type?: string
+  alt?: string | null
+  position?: number
+  variant_ids?: string[]
+  focal_point_x?: number | null
+  focal_point_y?: number | null
+  external_video_url?: string | null
+  video_url?: string | null
+  video_embed_url?: string | null
+  poster_url?: string | null
+  original_url?: string | null
+  mini_url?: string | null
+  small_url?: string | null
+  medium_url?: string | null
+  large_url?: string | null
+  xlarge_url?: string | null
+  download_url?: string | null
+}
+
+export interface PanelVariant {
+  id: string
+  sku?: string | null
+  barcode?: string | null
+  options_text?: string
+  position?: number
+  price?: { amount?: string | null; currency?: string | null } | null
+  prices?: Array<{
+    amount?: string | null
+    currency?: string | null
+    compare_at_amount?: string | null
+  }>
+  cost_price?: string | null
+  cost_currency?: string | null
+  weight?: number | null
+  height?: number | null
+  width?: number | null
+  depth?: number | null
+  weight_unit?: string | null
+  dimensions_unit?: string | null
+  hs_code?: string | null
+  country_of_origin?: string | null
+  customs_description?: string | null
+  minimum_order_quantity?: number | null
+  order_multiple?: number | null
+  purchase_unit?: string | null
+  units_per_carton?: number | null
+  cartons_per_pallet?: number | null
+  carton_weight?: string | number | null
+  carton_package_type_id?: string | null
+  track_inventory?: boolean
+  preorderable?: boolean
+  preorder_ships_at?: string | null
+  backorder_limit?: number | null
+  total_on_hand?: number | null
+  available_stock?: number | null
+  option_values?: Array<{ id: string; name: string; option_type_name: string }>
+  stock_levels?: PanelStockLevel[]
+  /** Marketplace configuration; a seller's serializer leaves these out. */
+  tax_category_id?: string | null
+  delivery_profile_id?: string | null
+}
+
+export interface PanelProduct {
+  id: string
+  name: string
+  slug?: string
+  status?: string
+  description?: string | null
+  description_html?: string | null
+  meta_title?: string | null
+  meta_description?: string | null
+  meta_keywords?: string | null
+  product_type_id?: string | null
+  variant_count?: number
+  /**
+   * Either shape: the operator's serializer expands the records, a seller's
+   * answers plain ids. The mapper reads whichever it was given.
+   */
+  category_ids?: string[]
+  collection_ids?: string[]
+  categories?: Array<{ id: string; name?: string }>
+  collections?: Array<{ id: string; name?: string; automatic?: boolean }>
+  tags?: string[]
+  metadata?: Record<string, unknown> | null
+  default_variant_id?: string
+  price?: { amount?: string | null; currency?: string | null } | null
+  variants?: PanelVariant[]
+  default_variant?: PanelVariant
+  media?: PanelMedia[]
+  custom_fields?: Array<{ id?: string; custom_field_definition_id: string; value?: unknown }>
+  /** Operator-only surfaces; absent on a seller's serializer. */
+  product_publications?: Array<{
+    id?: string
+    channel_id: string
+    published_at?: string | null
+    unpublished_at?: string | null
+  }>
+  tax_category_id?: string | null
+  /** Both panels: a seller picks a profile from the marketplace's list. */
+  delivery_profile_id?: string | null
+}
+
+/**
+ * One shelf's worth of a variant — the count and where it sits, which is all
+ * the form reads.
+ */
+export interface PanelStockLevel {
+  id?: string
+  stock_location_id: string | null
+  stock_location_name?: string | null
+  stock_location?: { id?: string; name?: string | null } | null
+  count_on_hand: number
+  backorderable: boolean
+}