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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
import { IMPORT_STATUSES, subsetOf } from '@spree/core'
import { toastManager } from '@spree/dashboard-ui'
import {
type QueryClient,
type QueryKey,
useMutation,
useQuery,
useQueryClient,
} from '@tanstack/react-query'
import { useEffect, useRef } from 'react'
import {
getApiClient,
type PanelImport,
type PanelImportCompleteMappingParams,
type PanelImportCreateParams,
type PanelImportDelimiter,
} from '../api-client'
import { downloadFromApi } from '../lib/download'
import { useResourceKey, useResourceKeyBuilder } from '../lib/query-keys'
import { useTenantId } from '../providers/tenant-provider'
import { useAuth } from './use-auth'
/** Statuses the wizard polls through — row creation and processing. */
const ACTIVE_STATUSES = subsetOf(IMPORT_STATUSES, ['completed_mapping', 'processing'])
const IMPORT_POLL_INTERVAL_MS = 2000
const ROWS_POLL_INTERVAL_MS = 5000
// Caches any import may have written to, plus `imports` itself (history table
// status column) and `translations` (product-translation CSV updates the
// coverage grid). Deliberately not per-type — imports are rare, so a few
// extra refetches beat maintaining a type → resource map (product rows alone
// fan out to option types/values and categories created on the fly).
//
// These are the operator dashboard's key names; a panel that names its lists
// differently adds its own through the client's `invalidateKeys`.
// Everything an import type can write. `price-lists` itself stays out: a
// list's own record does not change when its prices do, and refetching it
// would reset the form under a merchant's unsaved edits.
const IMPORT_TOUCHED_RESOURCES = [
'products',
'option-types',
'categories',
'customers',
'imports',
'translations',
'prices',
'catalogs',
]
/** Whether the import's pipeline is still running (the poll's continue predicate). */
export function isImportActive(status: string | undefined): boolean {
return !!status && ACTIVE_STATUSES.includes(status)
}
/**
* Marks every cache an import can have written as stale. The pipeline writes
* records server-side, outside any tracked mutation, so nothing else ever
* does; called when an import finishes, and when its wizard is closed while
* it is still running (after which nothing is left to see it finish).
*/
export function invalidateImportTouchedResources(
queryClient: QueryClient,
buildKey: (resource: string) => QueryKey,
) {
const extraKeys = getApiClient().imports?.invalidateKeys
for (const resource of new Set([...IMPORT_TOUCHED_RESOURCES, ...(extraKeys ?? [])])) {
queryClient.invalidateQueries({ queryKey: buildKey(resource) })
}
}
/**
* The panel's import resource.
*
* Throws rather than returning undefined: every hook here is reached from UI
* that only renders when the panel registered one, so a miss is a boot
* misconfiguration and should say so where it happens.
*/
function imports() {
const resource = getApiClient().imports
if (!resource) {
throw new Error(
'@spree/dashboard-core: this panel registered no `imports` client. ' +
'Add one in setApiClient(...) before rendering import UI.',
)
}
return resource
}
/** Create-time parameters beyond the ones every import shares. */
export type ImportCreateExtras = Omit<
PanelImportCreateParams,
'type' | 'attachment_signed_id' | 'delimiter' | 'results_url'
>
export interface CreateImportInput {
type: string
/** The `signed_id` of the already uploaded CSV (see `FileUploadField`). */
signedId: string
preferredDelimiter?: PanelImportDelimiter
/**
* Whatever else the import type needs at create — the price list a
* `price_list_prices` import merges into, say. Passed through untouched.
*/
params?: ImportCreateExtras
/**
* Where the import-done email should link back to. Defaults to this panel's
* own imports view under the current tenant.
*/
resultsPath?: string
}
/**
* Creates the import from an uploaded CSV; the response is in the
* `mapping` state and carries the mapping payload.
*/
export function useCreateImport() {
const tenantId = useTenantId()
return useMutation({
mutationFn: ({
type,
signedId,
preferredDelimiter,
params,
resultsPath,
}: CreateImportInput): Promise<PanelImport> =>
imports().create({
...params,
type,
attachment_signed_id: signedId,
delimiter: preferredDelimiter,
// The import-done email deep-links back to the wizard (`?import=<id>`
// appended server-side). Only honored when this origin is on the
// store's allowed-origins list.
results_url: `${window.location.origin}${resultsPath ?? `/${tenantId}/settings/imports`}`,
}),
})
}
/**
* Single import, polled every 2s while the pipeline is running. `mapping`
* (user-driven) and terminal statuses don't poll — a mapping-state refetch
* would re-read the attached CSV server-side on every tick.
*
* A finished import (completed, or failed — earlier rows may still have been
* written) invalidates every cache imports can touch: the pipeline writes
* records server-side, outside any tracked mutation, so nothing else ever
* marks those lists stale and "View products" would keep serving the
* pre-import cache.
*/
export function useImport(id: string) {
const queryClient = useQueryClient()
const buildKey = useResourceKeyBuilder()
const query = useQuery({
queryKey: useResourceKey('imports', id),
queryFn: () => imports().get(id),
enabled: !!id,
refetchInterval: (query) =>
isImportActive(query.state.data?.status) ? IMPORT_POLL_INTERVAL_MS : false,
})
// Fires when the poll lands on a finished status — including again after
// each retry pass (`finished` flips false → true anew). Reopening an
// already-finished import refires it; harmless, invalidation is idempotent.
const status = query.data?.status
const finished = status === 'completed' || status === 'failed'
useEffect(() => {
if (finished) invalidateImportTouchedResources(queryClient, buildKey)
}, [finished, queryClient, buildKey])
// Unmounted while the import is still running — the wizard closed, or the
// merchant navigated away — nothing is left to see it finish, so the caches
// it will have written are marked stale now. An import the poll has not
// answered for yet counts as running: nothing says it is finished.
const unfinished = useRef(true)
unfinished.current = !finished
useEffect(
() => () => {
if (unfinished.current) invalidateImportTouchedResources(queryClient, buildKey)
},
[queryClient, buildKey],
)
return query
}
/** Rows of an import (the failure report), optionally polled while processing. */
export function useImportRows(
importId: string,
params: Record<string, unknown>,
options?: { poll?: boolean },
) {
return useQuery({
queryKey: useResourceKey('imports', importId, 'rows', params),
queryFn: () => imports().rows.list(importId, params),
enabled: !!importId,
refetchInterval: options?.poll ? ROWS_POLL_INTERVAL_MS : false,
placeholderData: (previous) => previous,
})
}
export function useCompleteMapping(id: string) {
const queryClient = useQueryClient()
const buildKey = useResourceKeyBuilder()
return useMutation({
mutationFn: (params?: PanelImportCompleteMappingParams) =>
imports().completeMapping(id, params),
onSuccess: (imp) => {
queryClient.setQueryData<PanelImport>(buildKey('imports', id), imp)
// Keep the history table's status column in sync.
queryClient.invalidateQueries({ queryKey: buildKey('imports') })
},
})
}
export function useRetryFailedRows(id: string) {
const queryClient = useQueryClient()
const buildKey = useResourceKeyBuilder()
return useMutation({
mutationFn: () => imports().retryFailedRows(id),
onSuccess: (imp) => {
queryClient.setQueryData<PanelImport>(buildKey('imports', id), imp)
// `refetchType: 'none'` refreshes the history list on its next mount
// without refetching the active wizard detail query: the retry response
// already carried the fresh `processing` status we just cached, and an
// immediate refetch would race the (fast) background retry job — often
// returning `completed` before the "Retrying failed rows" state is ever
// rendered. Marking stale keeps the poll as the single source of the
// completion transition.
queryClient.invalidateQueries({ queryKey: buildKey('imports'), refetchType: 'none' })
},
onError: (err) => {
toastManager.add({ type: 'error', title: err instanceof Error ? err.message : String(err) })
},
})
}
export function useDeleteImport() {
const queryClient = useQueryClient()
const buildKey = useResourceKeyBuilder()
return useMutation({
mutationFn: (id: string) => imports().delete(id),
onSuccess: (_data, id) => {
queryClient.removeQueries({ queryKey: buildKey('imports', id) })
queryClient.invalidateQueries({ queryKey: buildKey('imports') })
},
onError: (err) => {
toastManager.add({ type: 'error', title: err instanceof Error ? err.message : String(err) })
},
})
}
/** Downloads the CSV template for an import type. */
export function useDownloadImportTemplate() {
const { token } = useAuth()
return useMutation({
mutationFn: (type: string) =>
downloadFromApi(
token,
imports().templateUrl(type),
'import_template.csv',
getApiClient().downloadHeaders?.() ?? {},
),
})
}
/**
* Downloads the populated example CSV for an import type.
*
* Goes through the API rather than linking the file directly: the URL is pinned
* to the installed Spree version so a released install never links to a newer,
* incompatible schema — and that version is deliberately not exposed over the
* API, since it would fingerprint the deployment. Returns 404 for a type that
* ships no example file.
*/
export function useDownloadImportExample() {
const { token } = useAuth()
return useMutation({
mutationFn: (type: string) =>
downloadFromApi(
token,
imports().exampleUrl(type),
`${type}.csv`,
getApiClient().downloadHeaders?.() ?? {},
),
})
}
/** Downloads the originally uploaded CSV of an import — the audit trail. */
export function useDownloadImportOriginal() {
const { token } = useAuth()
return useMutation({
mutationFn: (imp: PanelImport) =>
downloadFromApi(
token,
imp.original_file_url ?? imports().downloadUrl(imp.id),
imp.original_filename ?? 'import.csv',
getApiClient().downloadHeaders?.() ?? {},
),
})
}