Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added external references to the dashboard metadata card (#15006)

Damian Legawiecf227994feffd
diff --git a/.changeset/dashboard-external-references.md b/.changeset/dashboard-external-references.md
new file mode 100644
index 0000000000..916b90a064
--- /dev/null
+++ b/.changeset/dashboard-external-references.md
@@ -0,0 +1,8 @@
+---
+"@spree/dashboard": patch
+"@spree/dashboard-core": patch
+"@spree/dashboard-ui": patch
+"@spree/admin-sdk": patch
+---
+
+The admin dashboard now shows external references (the keys an ERP, PIM or CRM knows a record by) in the Metadata card, each with a copy button. They appear on product, order, category, company and seller pages, in the metadata sheet of returns and fulfillments, and in the stock location edit panel. The Admin API now returns external references for sellers too.
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index a4a5a18efb..68866ed8ad 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -53667,6 +53667,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: pending
contact_email: [email protected]
billing_email:
@@ -53783,6 +53784,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: pending
contact_email: [email protected]
billing_email:
@@ -53891,6 +53893,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: pending
contact_email: [email protected]
billing_email:
@@ -53985,6 +53988,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: pending
contact_email: [email protected]
billing_email:
@@ -54175,6 +54179,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: invited
contact_email: [email protected]
billing_email:
@@ -54269,6 +54274,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: approved
contact_email: [email protected]
billing_email:
@@ -54375,6 +54381,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: onboarding
contact_email: [email protected]
billing_email:
@@ -54489,6 +54496,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: suspended
contact_email: [email protected]
billing_email:
@@ -54585,6 +54593,7 @@ paths:
logo_url:
square_logo_url:
cover_photo_url:
+ external_references: {}
status: rejected
contact_email: [email protected]
billing_email:
@@ -70903,6 +70912,8 @@ components:
type: array
items:
"$ref": "#/components/schemas/CustomField"
+ external_references:
+ type: object
status:
anyOf:
- type: string
@@ -70988,6 +70999,7 @@ components:
- logo_url
- square_logo_url
- cover_photo_url
+ - external_references
- status
- contact_email
- billing_email
diff --git a/docs/developer/core-concepts/external-references.mdx b/docs/developer/core-concepts/external-references.mdx
index c9da96e43f..edcd88536d 100644
--- a/docs/developer/core-concepts/external-references.mdx
+++ b/docs/developer/core-concepts/external-references.mdx
@@ -109,7 +109,7 @@ What a write changes:
## Reading references
-Admin API responses for every record above except sellers include `external_references` as a flat map — the same shape you send:
+Admin API responses for every record above include `external_references` as a flat map — the same shape you send:
```json Response
{
@@ -124,7 +124,7 @@ Admin API responses for every record above except sellers include `external_refe
External references never appear in the Store API. Which ERP a merchant runs, and the keys records have in it, is back-office information.
-In the dashboard, references show in the **JSON** view on each record's detail page. There is no form for editing them: they are written by integrations and read by whoever is debugging a sync.
+In the dashboard, references show in the **Metadata** card, above the record's metadata, with a button to copy each key. The card sits at the end of the detail page for products, orders, categories, companies and sellers; returns and fulfillments show it from **View metadata** in their row menu, and stock locations at the bottom of their edit panel. There is no form for editing references: integrations write them, and people read them when tracing a record to another system.
## Addressing records by your keys
diff --git a/packages/admin-sdk/src/types/generated/Seller.ts b/packages/admin-sdk/src/types/generated/Seller.ts
index 2632ebe960..9c5a91e3be 100644
--- a/packages/admin-sdk/src/types/generated/Seller.ts
+++ b/packages/admin-sdk/src/types/generated/Seller.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 6b3680f8ee21ed3845d5fc9b9d7067f4
+// Typelizer digest 2146944d7b246f921f8a0dd4c20073a4
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {CustomField, Address, SellerStatus, TaxRemittance, PayoutScheduleInterval} from '@/types'
@@ -13,6 +13,7 @@ interface Seller {
square_logo_url: string | null;
cover_photo_url: string | null;
custom_fields?: Array<CustomField>;
+ external_references: Record<string, string>;
status: SellerStatus;
contact_email: string | null;
billing_email: string | null;
diff --git a/packages/admin-sdk/src/zod/generated/Seller.ts b/packages/admin-sdk/src/zod/generated/Seller.ts
index dcb53fe183..62532ea554 100644
--- a/packages/admin-sdk/src/zod/generated/Seller.ts
+++ b/packages/admin-sdk/src/zod/generated/Seller.ts
@@ -13,6 +13,7 @@ export const SellerSchema = z.object({
square_logo_url: z.string().nullable(),
cover_photo_url: z.string().nullable(),
custom_fields: z.array(CustomFieldSchema).optional(),
+ external_references: z.record(z.string(), z.string()),
status: z.string(),
contact_email: z.string().nullable(),
billing_email: z.string().nullable(),
diff --git a/packages/dashboard-core/src/api-client.ts b/packages/dashboard-core/src/api-client.ts
index 8cdc27b60f..2319fc3370 100644
--- a/packages/dashboard-core/src/api-client.ts
+++ b/packages/dashboard-core/src/api-client.ts
@@ -655,6 +655,8 @@ export interface PanelStockLocation {
pickup_stock_policy?: string
pickup_ready_in_minutes?: number | null
pickup_instructions?: string | null
+ /** Operator-only; the seller panel's serializer leaves it out. */
+ external_references?: Record<string, string>
}
/**
diff --git a/packages/dashboard-core/src/components/record-metadata.tsx b/packages/dashboard-core/src/components/record-metadata.tsx
index 84737b9789..1961f0497f 100644
--- a/packages/dashboard-core/src/components/record-metadata.tsx
+++ b/packages/dashboard-core/src/components/record-metadata.tsx
@@ -1,19 +1,46 @@
-import { DropdownMenuItem, hasMetadata, MetadataCard, MetadataSheet } from '@spree/dashboard-ui'
+import {
+ DropdownMenuItem,
+ hasExternalReferences,
+ hasMetadata,
+ MetadataCard,
+ MetadataSheet,
+} from '@spree/dashboard-ui'
import { BracesIcon } from '@spree/dashboard-ui/icons'
import { useState } from 'react'
import { useTranslation } from 'react-i18next'
type Metadata = Record<string, unknown> | null | undefined
+type ExternalReferences = Record<string, string> | null | undefined
-/** Metadata card for the main column of a record's detail page. */
-export function RecordMetadataCard({ metadata }: { metadata: Metadata }) {
+interface RecordIntegrationData {
+ metadata?: Metadata
+ /** The record's `external_references` map, on records that carry one. */
+ externalReferences?: ExternalReferences
+}
+
+function useMetadataCopy() {
const { t } = useTranslation()
+ return {
+ title: t('admin.components.metadata_card.title'),
+ metadataTitle: t('admin.components.metadata_card.title'),
+ externalReferencesTitle: t('admin.components.metadata_card.external_references'),
+ copyLabel: (system: string) => t('admin.components.metadata_card.copy_reference', { system }),
+ emptyTitle: t('admin.components.metadata_card.empty_title'),
+ emptyDescription: t('admin.components.metadata_card.empty_description'),
+ }
+}
+
+function hasIntegrationData({ metadata, externalReferences }: RecordIntegrationData) {
+ return hasMetadata(metadata) || hasExternalReferences(externalReferences)
+}
+
+/** Metadata card for the main column of a record's detail page. */
+export function RecordMetadataCard({ metadata, externalReferences }: RecordIntegrationData) {
return (
<MetadataCard
metadata={metadata}
- title={t('admin.components.metadata_card.title')}
- emptyTitle={t('admin.components.metadata_card.empty_title')}
- emptyDescription={t('admin.components.metadata_card.empty_description')}
+ externalReferences={externalReferences}
+ {...useMetadataCopy()}
/>
)
}
@@ -21,26 +48,24 @@ export function RecordMetadataCard({ metadata }: { metadata: Metadata }) {
/** Metadata of a row inside another page; pair with {@link ViewMetadataMenuItem}. */
function RecordMetadataSheet({
metadata,
+ externalReferences,
open,
onOpenChange,
description,
-}: {
- metadata: Metadata
+}: RecordIntegrationData & {
open: boolean
onOpenChange: (open: boolean) => void
/** Names the record, e.g. "Payment P123". */
description?: string
}) {
- const { t } = useTranslation()
return (
<MetadataSheet
open={open}
onOpenChange={onOpenChange}
metadata={metadata}
- title={t('admin.components.metadata_card.title')}
+ externalReferences={externalReferences}
description={description}
- emptyTitle={t('admin.components.metadata_card.empty_title')}
- emptyDescription={t('admin.components.metadata_card.empty_description')}
+ {...useMetadataCopy()}
/>
)
}
@@ -51,17 +76,18 @@ function RecordMetadataSheet({
* closed, so it never flashes the empty state on the way out.
*/
export function useMetadataSheet() {
- const [viewing, setViewing] = useState<{ metadata: Metadata; description?: string }>()
+ const [viewing, setViewing] = useState<RecordIntegrationData & { description?: string }>()
const [open, setOpen] = useState(false)
return {
- show(metadata: Metadata, description?: string) {
- setViewing({ metadata, description })
+ show(metadata: Metadata, description?: string, externalReferences?: ExternalReferences) {
+ setViewing({ metadata, description, externalReferences })
setOpen(true)
},
sheet: (
<RecordMetadataSheet
metadata={viewing?.metadata}
+ externalReferences={viewing?.externalReferences}
description={viewing?.description}
open={open}
onOpenChange={setOpen}
@@ -72,14 +98,11 @@ export function useMetadataSheet() {
/** Renders nothing when the record has no metadata, so a menu needs no check of its own. */
export function ViewMetadataMenuItem({
- metadata,
onClick,
-}: {
- metadata: Metadata
- onClick: () => void
-}) {
+ ...data
+}: RecordIntegrationData & { onClick: () => void }) {
const { t } = useTranslation()
- if (!hasMetadata(metadata)) return null
+ if (!hasIntegrationData(data)) return null
return (
<DropdownMenuItem onClick={onClick}>
@@ -90,6 +113,6 @@ export function ViewMetadataMenuItem({
}
/** Metadata at the bottom of a record's edit sheet; renders nothing when there is none. */
-export function RecordMetadataSection({ metadata }: { metadata: Metadata }) {
- return hasMetadata(metadata) ? <RecordMetadataCard metadata={metadata} /> : null
+export function RecordMetadataSection(data: RecordIntegrationData) {
+ return hasIntegrationData(data) ? <RecordMetadataCard {...data} /> : null
}
diff --git a/packages/dashboard-core/src/locales/ar.json b/packages/dashboard-core/src/locales/ar.json
index a07f2bbba5..8f05a8e190 100644
--- a/packages/dashboard-core/src/locales/ar.json
+++ b/packages/dashboard-core/src/locales/ar.json
@@ -366,8 +366,10 @@
"video_title": "معاينة الفيديو"
},
"metadata_card": {
+ "copy_reference": "نسخ مفتاح {{system}}",
"empty_description": "تملأ التطبيقات والتكاملات هذا تلقائيًا.",
"empty_title": "لا توجد بيانات وصفية",
+ "external_references": "المراجع الخارجية",
"title": "البيانات الوصفية",
"view": "عرض البيانات الوصفية"
},
diff --git a/packages/dashboard-core/src/locales/de.json b/packages/dashboard-core/src/locales/de.json
index 54b44b62e3..68f236789a 100644
--- a/packages/dashboard-core/src/locales/de.json
+++ b/packages/dashboard-core/src/locales/de.json
@@ -366,8 +366,10 @@
"video_title": "Videovorschau"
},
"metadata_card": {
+ "copy_reference": "{{system}}-Schlüssel kopieren",
"empty_description": "Apps und Integrationen füllen dies automatisch.",
"empty_title": "Keine Metadaten",
+ "external_references": "Externe Referenzen",
"title": "Metadaten",
"view": "Metadaten anzeigen"
},
diff --git a/packages/dashboard-core/src/locales/en.json b/packages/dashboard-core/src/locales/en.json
index 0c5eea689f..84da7d4869 100644
--- a/packages/dashboard-core/src/locales/en.json
+++ b/packages/dashboard-core/src/locales/en.json
@@ -368,8 +368,10 @@
"video_title": "Video preview"
},
"metadata_card": {
+ "copy_reference": "Copy {{system}} key",
"empty_description": "Apps and integrations populate this automatically.",
"empty_title": "No metadata",
+ "external_references": "External references",
"title": "Metadata",
"view": "View metadata"
},
diff --git a/packages/dashboard-core/src/locales/es.json b/packages/dashboard-core/src/locales/es.json
index e955bd38d6..93b76d0283 100644
--- a/packages/dashboard-core/src/locales/es.json
+++ b/packages/dashboard-core/src/locales/es.json
@@ -179,8 +179,10 @@
"video_title": "Vista previa del video"
},
"metadata_card": {
+ "copy_reference": "Copiar clave de {{system}}",
"empty_description": "Las aplicaciones e integraciones lo completan automáticamente.",
"empty_title": "Sin metadatos",
+ "external_references": "Referencias externas",
"title": "Metadatos",
"view": "Ver metadatos"
},
diff --git a/packages/dashboard-core/src/locales/fr.json b/packages/dashboard-core/src/locales/fr.json
index 5c6cdcc75b..42e9a64b50 100644
--- a/packages/dashboard-core/src/locales/fr.json
+++ b/packages/dashboard-core/src/locales/fr.json
@@ -366,8 +366,10 @@
"video_title": "Aperçu de la vidéo"
},
"metadata_card": {
+ "copy_reference": "Copier la clé {{system}}",
"empty_description": "Les applications et intégrations remplissent ceci automatiquement.",
"empty_title": "Aucune métadonnée",
+ "external_references": "Références externes",
"title": "Métadonnées",
"view": "Voir les métadonnées"
},
diff --git a/packages/dashboard-core/src/locales/pl.json b/packages/dashboard-core/src/locales/pl.json
index 154cdeea4e..43dcf408c9 100644
--- a/packages/dashboard-core/src/locales/pl.json
+++ b/packages/dashboard-core/src/locales/pl.json
@@ -367,8 +367,10 @@
"video_title": "Podgląd wideo"
},
"metadata_card": {
+ "copy_reference": "Kopiuj klucz {{system}}",
"empty_description": "Aplikacje i integracje wypełniają to automatycznie.",
"empty_title": "Brak metadanych",
+ "external_references": "Odwołania zewnętrzne",
"title": "Metadane",
"view": "Pokaż metadane"
},
diff --git a/packages/dashboard-core/src/locales/zh-CN.json b/packages/dashboard-core/src/locales/zh-CN.json
index 110d926ac5..be5f8ddaab 100644
--- a/packages/dashboard-core/src/locales/zh-CN.json
+++ b/packages/dashboard-core/src/locales/zh-CN.json
@@ -366,8 +366,10 @@
"video_title": "视频预览"
},
"metadata_card": {
+ "copy_reference": "复制 {{system}} 键",
"empty_description": "应用和集成会自动填充此内容。",
"empty_title": "暂无元数据",
+ "external_references": "外部引用",
"title": "元数据",
"view": "查看元数据"
},
diff --git a/packages/dashboard-core/src/pages/stock-locations.tsx b/packages/dashboard-core/src/pages/stock-locations.tsx
index 06ecec8cf7..830b272142 100644
--- a/packages/dashboard-core/src/pages/stock-locations.tsx
+++ b/packages/dashboard-core/src/pages/stock-locations.tsx
@@ -33,6 +33,7 @@ import type { PanelStockLocation } from '../api-client'
import { Can } from '../components/can'
import { CountryCombobox } from '../components/country-combobox'
import { StateCombobox, useCountryStates } from '../components/country-state-fields'
+import { RecordMetadataSection } from '../components/record-metadata'
import { ResourceTable, resourceSearchSchema } from '../components/resource-table'
import { HostFormSlot } from '../components/slot'
import {
@@ -341,6 +342,7 @@ function EditStockLocationSheet({
/>
{StockLevelsPanel && <StockLevelsPanel stockLocationId={id} />}
{ActivityPanel && <ActivityPanel stockLocationId={id} />}
+ <RecordMetadataSection externalReferences={stockLocation?.external_references} />
</div>
<SheetFooter>
<Button
diff --git a/packages/dashboard-ui/src/spree/metadata/metadata-card.tsx b/packages/dashboard-ui/src/spree/metadata/metadata-card.tsx
index 96958b1e8c..3be542a9f4 100644
--- a/packages/dashboard-ui/src/spree/metadata/metadata-card.tsx
+++ b/packages/dashboard-ui/src/spree/metadata/metadata-card.tsx
@@ -2,6 +2,7 @@ import { Fragment } from 'react'
import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '../../ui/empty'
import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from '../../ui/sheet'
import { CollapsibleCard } from '../collapsible-card'
+import { CopyToClipboardButton } from '../copy-to-clipboard-button'
import { BracesIcon } from '../icons'
/**
@@ -10,19 +11,45 @@ import { BracesIcon } from '../icons'
*/
type Metadata = Record<string, unknown> | null | undefined
+/** The keys external systems (ERP, PIM, CRM) know a record by, as `{ system => key }`. */
+type ExternalReferences = Record<string, string> | null | undefined
+
interface MetadataListProps {
metadata: Metadata
+ externalReferences?: ExternalReferences
/** Translated copy (passed by the app — these components stay headless). */
emptyTitle: string
emptyDescription: string
+ /** Section headings, shown only when the record has both kinds of data. */
+ metadataTitle?: string
+ externalReferencesTitle?: string
+ /** Accessible label for the copy button next to a system's key. */
+ copyLabel?: (system: string) => string
}
export function hasMetadata(metadata: Metadata): metadata is Record<string, unknown> {
return !!metadata && Object.keys(metadata).length > 0
}
-export function MetadataList({ metadata, emptyTitle, emptyDescription }: MetadataListProps) {
- if (!hasMetadata(metadata)) {
+export function hasExternalReferences(
+ externalReferences: ExternalReferences,
+): externalReferences is Record<string, string> {
+ return !!externalReferences && Object.keys(externalReferences).length > 0
+}
+
+export function MetadataList({
+ metadata,
+ externalReferences,
+ emptyTitle,
+ emptyDescription,
+ metadataTitle,
+ externalReferencesTitle,
+ copyLabel,
+}: MetadataListProps) {
+ const showMetadata = hasMetadata(metadata)
+ const showReferences = hasExternalReferences(externalReferences)
+
+ if (!showMetadata && !showReferences) {
return (
<Empty className="border-0 p-0">
<EmptyHeader>
@@ -36,17 +63,52 @@ export function MetadataList({ metadata, emptyTitle, emptyDescription }: Metadat
)
}
+ const both = showMetadata && showReferences
+
return (
- <dl className="grid grid-cols-[minmax(160px,1fr)_2fr] gap-x-4 gap-y-2 text-sm">
- {Object.entries(metadata).map(([key, value]) => (
- <Fragment key={key}>
- <dt>
- <code className="text-xs text-muted-foreground">{key}</code>
- </dt>
- <dd className="text-foreground/90 break-words font-mono text-xs">{formatValue(value)}</dd>
- </Fragment>
- ))}
- </dl>
+ <div className="flex flex-col gap-4">
+ {showReferences && (
+ <section className="flex flex-col gap-2">
+ {externalReferencesTitle && (
+ <h4 className="text-xs font-medium text-muted-foreground">{externalReferencesTitle}</h4>
+ )}
+ <dl className="grid grid-cols-[minmax(160px,1fr)_2fr] items-center gap-x-4 gap-y-1 text-sm">
+ {Object.entries(externalReferences).map(([system, key]) => (
+ <Fragment key={system}>
+ <dt>
+ <code className="text-xs text-muted-foreground">{system}</code>
+ </dt>
+ <dd className="flex min-w-0 items-center gap-1 font-mono text-xs text-foreground/90">
+ <span className="break-all">{key}</span>
+ {copyLabel && (
+ <CopyToClipboardButton value={key} aria-label={copyLabel(system)} />
+ )}
+ </dd>
+ </Fragment>
+ ))}
+ </dl>
+ </section>
+ )}
+ {showMetadata && (
+ <section className="flex flex-col gap-2">
+ {both && metadataTitle && (
+ <h4 className="text-xs font-medium text-muted-foreground">{metadataTitle}</h4>
+ )}
+ <dl className="grid grid-cols-[minmax(160px,1fr)_2fr] gap-x-4 gap-y-2 text-sm">
+ {Object.entries(metadata).map(([key, value]) => (
+ <Fragment key={key}>
+ <dt>
+ <code className="text-xs text-muted-foreground">{key}</code>
+ </dt>
+ <dd className="text-foreground/90 break-words font-mono text-xs">
+ {formatValue(value)}
+ </dd>
+ </Fragment>
+ ))}
+ </dl>
+ </section>
+ )}
+ </div>
)
}
@@ -54,13 +116,16 @@ interface MetadataCardProps extends MetadataListProps {
title: string
}
-/** Folded by default: metadata is for integrations, and the key count says whether there is any. */
+/** Folded by default: metadata is for integrations, and the entry count says whether there is any. */
export function MetadataCard({ title, ...listProps }: MetadataCardProps) {
return (
<CollapsibleCard
title={title}
icon={<BracesIcon className="size-4" />}
- count={Object.keys(listProps.metadata ?? {}).length}
+ count={
+ Object.keys(listProps.metadata ?? {}).length +
+ Object.keys(listProps.externalReferences ?? {}).length
+ }
>
<MetadataList {...listProps} />
</CollapsibleCard>
diff --git a/packages/dashboard/e2e/metadata.spec.ts b/packages/dashboard/e2e/metadata.spec.ts
index 7bd059d825..75f242e990 100644
--- a/packages/dashboard/e2e/metadata.spec.ts
+++ b/packages/dashboard/e2e/metadata.spec.ts
@@ -10,14 +10,16 @@ import {
seedRecord,
} from './helpers'
-// Metadata is written by apps and integrations, never in the dashboard, so
-// every record here is seeded with it through the Admin API.
+// Metadata and external references are written by apps and integrations,
+// never in the dashboard, so every record here is seeded through the Admin API.
const METADATA = { erp_id: 'ERP-4711' }
+const EXTERNAL_REFERENCES = { netsuite: 'NS-0042' }
async function seedCompany(page: Parameters<typeof login>[0], session: E2ELoginSession) {
return seedRecord(page, session, '/companies', {
name: `E2E Metadata Co ${Date.now()}`,
metadata: METADATA,
+ external_references: EXTERNAL_REFERENCES,
})
}
@@ -30,20 +32,23 @@ test.describe('metadata', () => {
await page.goto(`/${session.store_id}/companies/${company.id}`)
- const toggle = page.getByRole('button', { name: /^metadata\s*1$/i })
+ const toggle = page.getByRole('button', { name: /^metadata\s*2$/i })
await expect(toggle).toBeVisible({ timeout: 15_000 })
await expect(page.getByText('ERP-4711')).toBeHidden()
await toggle.click()
await expect(page.getByText('erp_id')).toBeVisible()
await expect(page.getByText('ERP-4711')).toBeVisible()
+ await expect(page.getByText('External references')).toBeVisible()
+ await expect(page.getByText('NS-0042')).toBeVisible()
+ await expect(page.getByRole('button', { name: /copy netsuite key/i })).toBeVisible()
})
test('a row menu opens the metadata of a nested record', async ({ page }) => {
const session = await login(page)
const order = await createPlacedOrder(page, session.accessToken)
const fulfillments = await adminRequest<{
- data: { fulfillment_items: { id: string }[] }[]
+ data: { id: string; fulfillment_items: { id: string }[] }[]
}>(page, session, 'get', `/orders/${order.id}/fulfillments?expand=fulfillment_items`)
const orderReturn = await adminRequest<{ id: string; number: string }>(
page,
@@ -56,7 +61,16 @@ test.describe('metadata', () => {
)
await adminRequest(page, session, 'patch', `/orders/${order.id}/returns/${orderReturn.id}`, {
metadata: METADATA,
+ external_references: EXTERNAL_REFERENCES,
})
+ // References alone are enough to offer the sheet.
+ await adminRequest(
+ page,
+ session,
+ 'patch',
+ `/orders/${order.id}/fulfillments/${fulfillments.data[0].id}`,
+ { external_references: { wms: 'SHIP-0042' } },
+ )
await page.goto(`/${session.store_id}/orders/${order.id}`)
const returns = page.locator('[data-slot="card"]').filter({ hasText: /^returns/i })
@@ -67,6 +81,35 @@ test.describe('metadata', () => {
const sheet = page.getByRole('dialog')
await expect(sheet.getByText('erp_id')).toBeVisible()
await expect(sheet.getByText('ERP-4711')).toBeVisible()
+ await expect(sheet.getByText('NS-0042')).toBeVisible()
+ await page.keyboard.press('Escape')
+ await expect(sheet).toBeHidden()
+
+ const fulfillmentsCard = page.locator('[data-slot="card"]').filter({
+ has: page.locator('[data-slot="card-title"]', { hasText: /fulfillments/i }),
+ })
+ await fulfillmentsCard
+ .getByRole('button', { name: /actions/i })
+ .first()
+ .click()
+ await page.getByRole('menuitem', { name: /view metadata/i }).click()
+ await expect(page.getByRole('dialog').getByText('SHIP-0042')).toBeVisible()
+ })
+
+ test('a seller page lists the keys external systems know it by', async ({ page }) => {
+ const session = await login(page)
+ const seller = await seedRecord(page, session, '/sellers', {
+ name: `E2E Referenced Seller ${Date.now()}`,
+ external_references: EXTERNAL_REFERENCES,
+ })
+
+ await page.goto(`/${session.store_id}/sellers/${seller.id}`)
+
+ const toggle = page.getByRole('button', { name: /^metadata\s*1$/i })
+ await expect(toggle).toBeVisible({ timeout: 15_000 })
+ await toggle.click()
+ await expect(page.getByText('netsuite')).toBeVisible()
+ await expect(page.getByText('NS-0042')).toBeVisible()
})
test('an edit sheet keeps metadata collapsed until opened', async ({ page }) => {
@@ -86,4 +129,24 @@ test.describe('metadata', () => {
await expect(sheet.getByText('erp_id')).toBeVisible()
await expect(sheet.getByText('ERP-4711')).toBeVisible()
})
+
+ test('an edit sheet shows external references on a record without metadata', async ({ page }) => {
+ const session = await login(page)
+ const name = `E2E Referenced Warehouse ${Date.now()}`
+ await seedRecord(page, session, '/stock_locations', {
+ name,
+ external_references: EXTERNAL_REFERENCES,
+ })
+
+ await gotoIndex(page, `/${session.store_id}/settings/stock-locations`, /add stock location/i)
+ await rowButton(page, name).click()
+
+ const sheet = page.getByRole('dialog')
+ const section = sheet.getByRole('button', { name: /^metadata\s*1$/i })
+ await expect(section).toBeVisible({ timeout: 15_000 })
+
+ await section.click()
+ await expect(sheet.getByText('netsuite')).toBeVisible()
+ await expect(sheet.getByText('NS-0042')).toBeVisible()
+ })
})
diff --git a/packages/dashboard/src/components/spree/categories/category-form.tsx b/packages/dashboard/src/components/spree/categories/category-form.tsx
index 8f6c27dead..dfe14d6c87 100644
--- a/packages/dashboard/src/components/spree/categories/category-form.tsx
+++ b/packages/dashboard/src/components/spree/categories/category-form.tsx
@@ -96,7 +96,10 @@ export function CategoryMain({
<FormBackedCustomFieldsProvider form={form} resourceType="category">
<CustomFieldsInlineCard collapsible />
</FormBackedCustomFieldsProvider>
- <RecordMetadataCard metadata={category.metadata} />
+ <RecordMetadataCard
+ metadata={category.metadata}
+ externalReferences={category.external_references}
+ />
</>
)}
</>
diff --git a/packages/dashboard/src/components/spree/order-returns-card.tsx b/packages/dashboard/src/components/spree/order-returns-card.tsx
index 900e86b965..9a825fcbfe 100644
--- a/packages/dashboard/src/components/spree/order-returns-card.tsx
+++ b/packages/dashboard/src/components/spree/order-returns-card.tsx
@@ -162,8 +162,13 @@ export function OrderReturnsCard({ order }: { order: Order }) {
)}
<ViewMetadataMenuItem
metadata={returnRecord.metadata}
+ externalReferences={returnRecord.external_references}
onClick={() =>
- metadataSheet.show(returnRecord.metadata, returnRecord.number)
+ metadataSheet.show(
+ returnRecord.metadata,
+ returnRecord.number,
+ returnRecord.external_references,
+ )
}
/>
{RETURN_CANCELABLE.includes(returnRecord.status) && (
diff --git a/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx b/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
index 79a2ce0382..e3b57e6371 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
@@ -520,7 +520,14 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
<ViewMetadataMenuItem
metadata={fulfillment.metadata}
- onClick={() => metadataSheet.show(fulfillment.metadata)}
+ externalReferences={fulfillment.external_references}
+ onClick={() =>
+ metadataSheet.show(
+ fulfillment.metadata,
+ fulfillment.number,
+ fulfillment.external_references,
+ )
+ }
/>
{CAN_CANCEL.includes(fulfillment.status) && (
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/companies/$companyId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/companies/$companyId.tsx
index 0360f67a22..dd06abba57 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/companies/$companyId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/companies/$companyId.tsx
@@ -159,7 +159,10 @@ function CompanyBody({ company }: { company: Company }) {
<MembersCard company={company} canEdit={canEdit} />
{!isDivision && <TaxExemptionCertificatesCard companyId={company.id} canEdit={canEdit} />}
<ApiCustomFieldsCard ownerType="company" ownerId={company.id} collapsible />
- <RecordMetadataCard metadata={company.metadata} />
+ <RecordMetadataCard
+ metadata={company.metadata}
+ externalReferences={company.external_references}
+ />
{/* Company-wide panels an extension owns: roles, purchase limits,
approval settings (docs: Enterprise b2b-companies plan). */}
<Slot name="company.form_main" context={{ company, kind: company.kind, canEdit }} />
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId/index.tsx
index 30bdbd915f..964894c623 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId/index.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId/index.tsx
@@ -90,7 +90,10 @@ function OrderDetailPage() {
>
<CustomFieldsInlineCard collapsible />
</EditableApiCustomFieldsProvider>
- <RecordMetadataCard metadata={order.metadata} />
+ <RecordMetadataCard
+ metadata={order.metadata}
+ externalReferences={order.external_references}
+ />
<Slot name="order.form_main" context={{ order }} />
</>
}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
index 2680014e58..dcf6cb4046 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
@@ -324,7 +324,10 @@ function ProductForm({ product }: { product: Product }) {
<ProductCustomFieldsProvider form={form} productTypeId={selectedProductTypeId}>
<CustomFieldsInlineCard collapsible />
</ProductCustomFieldsProvider>
- <RecordMetadataCard metadata={product.metadata} />
+ <RecordMetadataCard
+ metadata={product.metadata}
+ externalReferences={product.external_references}
+ />
<Slot name="product.form_main" context={{ product, mode: 'edit' }} />
</>
}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/sellers/$sellerId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/sellers/$sellerId.tsx
index 9a6dfd294c..ae0f62c77f 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/sellers/$sellerId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/sellers/$sellerId.tsx
@@ -295,7 +295,10 @@ function SellerBody({ seller }: { seller: Seller }) {
<SellerOnboardingCard seller={seller} canEdit={canEdit} />
<SellerTeamCard seller={seller} onInvite={() => setInviting(true)} />
<ApiCustomFieldsCard ownerType="seller" ownerId={seller.id} collapsible />
- <RecordMetadataCard metadata={seller.metadata} />
+ <RecordMetadataCard
+ metadata={seller.metadata}
+ externalReferences={seller.external_references}
+ />
<Slot name="seller.form_main" context={{ seller, canEdit }} />
</>
}
diff --git a/spree/api/app/controllers/spree/api/v3/admin/sellers_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/sellers_controller.rb
index eb5b05ce6e..db67c4233a 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/sellers_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/sellers_controller.rb
@@ -195,7 +195,7 @@ module Spree
# every seller on the page, so it loads once. Applied to the scope
# rather than the collection so a single-seller read gets it too.
def scope_includes
- [:billing_address, :requirement_submissions, { stock_locations: [] },
+ [:billing_address, :requirement_submissions, :external_references, { stock_locations: [] },
{ store: :seller_requirements, logo_attachment: :blob, cover_photo_attachment: :blob }]
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/seller_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/seller_serializer.rb
index 0c978887d9..2c651c138a 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/seller_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/seller_serializer.rb
@@ -6,6 +6,8 @@ module Spree
# shopper also gets, plus the operational state and the settlement and
# tax configuration only the operator sets.
class SellerSerializer < V3::SellerSerializer
+ include Concerns::ExternalReferencesAttribute
+
typelize status: [:string, enum: Spree::Seller.statuses, enum_type_name: 'SellerStatus'],
legal_name: [:string, nullable: true],
registration_number: [:string, nullable: true],
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb
index 01da38e408..de41516326 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb
@@ -109,6 +109,14 @@ RSpec.describe Spree::Api::V3::Admin::SellersController, type: :controller do
expect(json_response['contact_email']).to eq('[email protected]')
end
+ it 'includes the keys external systems know the seller by' do
+ seller.set_external_id('stripe_connect', 'acct_123')
+
+ get :show, params: { id: seller.prefixed_id }, as: :json
+
+ expect(json_response['external_references']).to eq('stripe_connect' => 'acct_123')
+ end
+
it "404s on another marketplace's seller" do
other = create(:seller, store: create(:store))