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

package/src/hooks/use-import.ts

@@ -1,15 +1,113 @@
-import type { Import, ImportCreateParams, ImportType } from '@spree/admin-sdk'
-import { useMutation } from '@tanstack/react-query'
-import { adminClient } from '../client'
+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 { useStore } from '../providers/store-provider'
+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 = new Set(['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.has(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' | 'preferred_delimiter' | 'results_url'
+>
+
 export interface CreateImportInput {
-  type: ImportType
+  type: string
   /** Signed blob id of the already direct-uploaded CSV (see `FileUploadField`). */
   signedId: string
-  preferredDelimiter?: ImportCreateParams['preferred_delimiter']
+  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
 }
 
 /**
@@ -17,32 +115,157 @@ export interface CreateImportInput {
  * `mapping` state and carries the mapping payload.
  */
 export function useCreateImport() {
-  const { storeId } = useStore()
+  const tenantId = useTenantId()
 
   return useMutation({
-    mutationFn: ({ type, signedId, preferredDelimiter }: CreateImportInput): Promise<Import> =>
-      adminClient.imports.create({
+    mutationFn: ({
+      type,
+      signedId,
+      preferredDelimiter,
+      params,
+      resultsPath,
+    }: CreateImportInput): Promise<PanelImport> =>
+      imports().create({
+        ...params,
         type,
         attachment: signedId,
         preferred_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}/${storeId}/settings/imports`,
+        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: ImportType) =>
+    mutationFn: (type: string) =>
       downloadFromApi(
         token,
-        `/api/v3/admin/imports/template?type=${encodeURIComponent(type)}`,
+        imports().templateUrl(type),
         'import_template.csv',
+        getApiClient().downloadHeaders?.() ?? {},
       ),
   })
 }
@@ -60,11 +283,12 @@ export function useDownloadImportExample() {
   const { token } = useAuth()
 
   return useMutation({
-    mutationFn: (type: ImportType) =>
+    mutationFn: (type: string) =>
       downloadFromApi(
         token,
-        `/api/v3/admin/imports/example?type=${encodeURIComponent(type)}`,
+        imports().exampleUrl(type),
         `${type}.csv`,
+        getApiClient().downloadHeaders?.() ?? {},
       ),
   })
 }
@@ -74,11 +298,12 @@ export function useDownloadImportOriginal() {
   const { token } = useAuth()
 
   return useMutation({
-    mutationFn: (imp: Import) =>
+    mutationFn: (imp: PanelImport) =>
       downloadFromApi(
         token,
-        imp.original_file_url ?? `/api/v3/admin/imports/${imp.id}/download`,
+        imp.original_file_url ?? imports().downloadUrl(imp.id),
         imp.original_filename ?? 'import.csv',
+        getApiClient().downloadHeaders?.() ?? {},
       ),
   })
 }

package/src/hooks/use-package-types.ts

@@ -0,0 +1,132 @@
+import type { PaginationMeta } from '@spree/dashboard-ui'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import i18n from 'i18next'
+import {
+  getApiClient,
+  type PanelPackageType,
+  type PanelPackageTypeCreateParams,
+  type PanelPackageTypeParams,
+  type PanelPackageTypeWrites,
+} from '../api-client'
+import { useResourceKey, useResourceKeyBuilder } from '../lib/query-keys'
+import { useResourceMutation } from './use-resource-mutation'
+
+/**
+ * The registered panel's package-type resource.
+ *
+ * Throws rather than answering undefined: every hook here is only reachable
+ * from the packaging page, and a panel that routes to it without registering
+ * the resource is misconfigured — failing at the call site says so far more
+ * clearly than a handful of "cannot read property of undefined" errors.
+ */
+function resource() {
+  const packageTypes = getApiClient().packageTypes
+  if (!packageTypes) {
+    throw new Error(
+      '@spree/dashboard-core: this panel registered no `packageTypes` resource, so the ' +
+        'package-types page cannot load. Add one in setApiClient(), or drop the route.',
+    )
+  }
+  return packageTypes
+}
+
+/**
+ * The same resource narrowed to the writing shape.
+ *
+ * The narrowing is checked once here rather than at each call site: the page
+ * only renders its sheets when `canWritePackageTypes()` is true, and the
+ * panel's registration is what makes that so.
+ */
+function writableResource(): PanelPackageTypeWrites {
+  const packageTypes = resource()
+  if (!('create' in packageTypes)) {
+    throw new Error(
+      '@spree/dashboard-core: this panel registered `packageTypes` reads only, so packaging ' +
+        'cannot be written. Register get/create/update, or drop the settings route.',
+    )
+  }
+  return packageTypes
+}
+
+export function usePackageType(id: string | undefined) {
+  return useQuery({
+    queryKey: useResourceKey('package-types', id ?? 'noop'),
+    queryFn: () => writableResource().get(id as string),
+    enabled: !!id,
+  })
+}
+
+export function useCreatePackageType() {
+  return useResourceMutation<PanelPackageType, Error, PanelPackageTypeCreateParams>({
+    mutationFn: (params) => writableResource().create(params),
+    invalidate: [['package-types'], ['panel-form-carton-package-types']],
+    successMessage: i18n.t('admin.package_types.messages.added'),
+    errorMessage: i18n.t('admin.errors.failed_to_create'),
+  })
+}
+
+export function useUpdatePackageType(id: string) {
+  return useResourceMutation<PanelPackageType, Error, PanelPackageTypeParams>({
+    mutationFn: (params) => writableResource().update(id, params),
+    invalidate: [['package-types'], ['package-types', id], ['panel-form-carton-package-types']],
+    successMessage: i18n.t('admin.package_types.messages.updated'),
+    errorMessage: i18n.t('admin.errors.failed_to_update'),
+  })
+}
+
+export function useDeletePackageType() {
+  const queryClient = useQueryClient()
+  const buildKey = useResourceKeyBuilder()
+
+  return useResourceMutation<void, Error, string>({
+    mutationFn: (id) => {
+      const remove = writableResource().delete
+      if (!remove) throw new Error('This panel cannot delete package types.')
+      return remove(id)
+    },
+    invalidate: [['package-types'], ['panel-form-carton-package-types']],
+    successMessage: i18n.t('admin.package_types.messages.deleted'),
+    errorMessage: i18n.t('admin.errors.failed_to_delete'),
+    onSuccess: (_data, id) => {
+      queryClient.removeQueries({ queryKey: buildKey('package-types', id) })
+    },
+  })
+}
+
+/**
+ * Whether this panel's API can write packaging at all. A panel registering
+ * only `list` gets the variant editor's carton picker and no settings page,
+ * so the page hides everything that would write.
+ */
+export function canWritePackageTypes(): boolean {
+  const packageTypes = getApiClient().packageTypes
+  if (packageTypes === undefined) return false
+
+  // All three, not just `create`: the page renders Edit off this answer, and
+  // a plain JavaScript host can register a partial object the write shape's
+  // type would have refused.
+  return ['get', 'create', 'update'].every((method) => method in packageTypes)
+}
+
+/** Whether this panel's API offers deletion, which not every one does. */
+export function canDeletePackageTypes(): boolean {
+  const packageTypes = getApiClient().packageTypes
+  return packageTypes !== undefined && 'delete' in packageTypes
+}
+
+/**
+ * One page of packaging, for `ResourceTable`'s own query. Not a hook — the
+ * table calls it with the search params it has already parsed.
+ */
+export function listPackageTypes(params: Record<string, unknown>) {
+  // `owner: 'mine'` — the settings page shows what this panel's principal
+  // owns, never another owner's rows. On the operator's panel every row is
+  // theirs and the param is ignored; on a seller's it hides the
+  // marketplace's shared packaging, which the seller reads through the
+  // variant editor's carton picker instead. A mixed list read as "packaging
+  // is configured" while the seller had recorded none.
+  return resource().list({ ...params, owner: 'mine' }) as Promise<{
+    data: PanelPackageType[]
+    meta: PaginationMeta
+  }>
+}

package/src/hooks/use-resource-mutation.ts

@@ -1,21 +1,21 @@
 import { SpreeError } from '@spree/admin-sdk'
+import { toastManager } from '@spree/dashboard-ui'
 import {
   type QueryKey,
   type UseMutationOptions,
   useMutation,
   useQueryClient,
 } from '@tanstack/react-query'
-import { toast } from 'sonner'
 import { i18n } from '../lib/i18n'
 import { withStoreScope } from '../lib/query-keys'
-import { useStore } from '../providers/store-provider'
+import { useTenantId } from '../providers/tenant-provider'
 
 interface UseResourceMutationOptions<TData, TError, TVariables>
   extends Omit<UseMutationOptions<TData, TError, TVariables>, 'onSuccess' | 'onError'> {
   /**
    * Query keys to invalidate after success. Pass logical keys without
-   * storeId (e.g. `[['channels'], ['channels', id]]`) — the hook injects the
-   * current storeId at position 1 automatically so invalidation matches the
+   * tenant id (e.g. `[['channels'], ['channels', id]]`) — the hook injects the
+   * current tenant id at position 1 automatically so invalidation matches the
    * store-scoped keys used by `ResourceTable` and other queries.
    *
    * Mutations that change setup-task state (see `Spree.store_setup_tasks` on
@@ -23,6 +23,18 @@ interface UseResourceMutationOptions<TData, TError, TVariables>
    * Started checklist and the nav progress badge stay live.
    */
   invalidate?: QueryKey[]
+  /**
+   * Key segments that must NOT be refreshed, even when `invalidate` matches
+   * them by prefix. `invalidate: [['categories', id]]` also sweeps nested
+   * lists like `['categories', id, 'products']`; passing `['products']` here
+   * holds those back.
+   *
+   * Use it where a parent's own save runs alongside writes to one of its
+   * nested collections: refreshing the collection from the parent's mutation
+   * lands mid-save, painting the pre-save rows for a frame before the real
+   * state arrives.
+   */
+  doNotInvalidate?: string[]
   /** Toast on success. Pass `false` to disable. Default `'Saved'`. */
   successMessage?: string | false
   /**
@@ -34,6 +46,12 @@ interface UseResourceMutationOptions<TData, TError, TVariables>
    * auth, gateway).
    */
   errorMessage?: string | false
+  /**
+   * Toast a field-level 422 too, joining its messages. Set this on a page
+   * with no form to render them inline — otherwise the rejection is silent
+   * and the merchant sees a button re-enable with no explanation.
+   */
+  showValidationErrors?: boolean
   /** Forwarded onSuccess callback. Runs after invalidation + toast. */
   onSuccess?: UseMutationOptions<TData, TError, TVariables>['onSuccess']
   /** Forwarded onError callback. Runs after error toast. */
@@ -59,11 +77,13 @@ export function useResourceMutation<TData = unknown, TError = Error, TVariables
   options: UseResourceMutationOptions<TData, TError, TVariables>,
 ) {
   const queryClient = useQueryClient()
-  const { storeId } = useStore()
+  const tenantId = useTenantId()
   const {
     invalidate,
+    doNotInvalidate,
     successMessage = i18n.t('admin.messages.saved'),
     errorMessage = i18n.t('admin.errors.generic'),
+    showValidationErrors = false,
     onSuccess,
     onError,
     ...rest
@@ -74,26 +94,67 @@ export function useResourceMutation<TData = unknown, TError = Error, TVariables
     onSuccess: (data, variables, onMutateResult, ctx) => {
       if (invalidate) {
         for (const key of invalidate) {
-          queryClient.invalidateQueries({ queryKey: withStoreScope(key, storeId) })
+          const scoped = withStoreScope(key, tenantId)
+          queryClient.invalidateQueries({
+            queryKey: scoped,
+            predicate: doNotInvalidate?.length
+              ? (query) => !query.queryKey.some((part) => doNotInvalidate.includes(part as string))
+              : undefined,
+          })
         }
       }
       if (successMessage !== false) {
-        toast.success(successMessage)
+        toastManager.add({ type: 'success', title: successMessage })
       }
       return onSuccess?.(data, variables, onMutateResult, ctx)
     },
     onError: (error, variables, onMutateResult, ctx) => {
-      if (errorMessage !== false && !isValidationError(error)) {
-        toast.error(errorMessage)
+      if (errorMessage !== false && showValidationErrors && isValidationError(error)) {
+        toastManager.add({ type: 'error', title: fieldMessages(error) ?? errorMessage })
+      } else if (errorMessage !== false && !isValidationError(error)) {
+        // A refusal with no field to hang off — a workflow saying the source
+        // shelf cannot cover this transfer — says something the caller's
+        // generic message does not, so it speaks for itself.
+        toastManager.add({ type: 'error', title: refusalMessage(error) ?? errorMessage })
       }
       return onError?.(error, variables, onMutateResult, ctx)
     },
   })
 }
 
-// 422 with `details` means the model rejected the payload (e.g., "Code can't
-// be blank"). The form renders these next to the offending input via
-// `mapSpreeErrorsToForm`, so toasting the same thing would just be noise.
+// 422 *with* `details` means the model rejected the payload field by field
+// (e.g. "Code can't be blank"). The form renders those next to the offending
+// input via `mapSpreeErrorsToForm`, so toasting them again would be noise.
+//
+// A 422 without `details` is a different animal: a workflow declining the
+// whole operation ("Only a transfer in transit can be received"). Nothing
+// renders it inline, so suppressing it leaves the merchant staring at a page
+// that silently did nothing.
 function isValidationError(error: unknown): boolean {
-  return error instanceof SpreeError && error.status === 422
+  return error instanceof SpreeError && error.status === 422 && hasFieldDetails(error)
+}
+
+function hasFieldDetails(error: SpreeError): boolean {
+  return !!error.details && Object.keys(error.details).length > 0
+}
+
+/** Every field message the server sent, as one line. */
+function fieldMessages(error: unknown): string | undefined {
+  if (!(error instanceof SpreeError) || !error.details) return undefined
+
+  const lines = Object.values(error.details).flatMap((entry) =>
+    (entry as Array<string | { message?: string }>).map((item) =>
+      typeof item === 'string' ? item : item?.message,
+    ),
+  )
+  const joined = lines.filter(Boolean).join('. ')
+
+  return joined || undefined
+}
+
+/** The server's own wording for a refusal that names no field. */
+function refusalMessage(error: unknown): string | undefined {
+  if (!(error instanceof SpreeError) || hasFieldDetails(error)) return undefined
+
+  return error.message || undefined
 }