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.

10.5 KB
Raw Blame
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?.() ?? {},
      ),
  })
}