Shared operations package

Shared functionality for import/export operations across multiple frontend applications and extensions.

Installation

pnpm add @commercetools-frontend-extensions/operations

Hooks

useFileUpload

A unified hook for file uploads that handles both the old flow (import container) and new flow (file import job).

const { upload, isUploading, progress, validationProgress } = useFileUpload({
  projectKey: string,
  useJobBasedFlow?: boolean,
  pollingInterval?: number,
  maxPollingAttempts?: number
})

Parameters:

• projectKey (required): The commercetools project key
• useJobBasedFlow (optional): Whether to use the job-based flow. Default: false
• pollingInterval (optional): Polling interval in ms for job-based flow. Default: 5000
• maxPollingAttempts (optional): Maximum polling attempts. Default: 200

Returns:

• upload - Function to start the upload
• isUploading - Whether upload is in progress
• progress - Upload progress (0-100)
• validationProgress - { processed: number, isValidating: boolean } (job-based flow only)
  • processed: Number of resources validated so far (from backend)
  • isValidating: Whether validation is in progress

Upload config options:

• file (required): The file to upload
• resourceType (required): The resource type
• fileType (optional): File type ('csv' or 'json') sent to the API.
• settings (optional): Import settings (format, decimal separator...)
• autoProcess (optional): When true, the backend automatically starts processing after validation completes (job-based flow only). Default: false
• skipValidationPolling (optional): When true, skips full validation polling and returns once the job reaches processing state. Useful for fire-and-forget uploads with autoProcess: true (job-based flow only). Default: false
• abortSignal (optional): AbortSignal for cancellation
• onSuccess (required): Callback when upload completes
• onError (optional): Callback for errors
• onProgress (optional): Callback for upload progress (0-100)
• onValidationProgress (optional): Callback for validation progress (job-based flow only)

Usage:

import { useFileUpload } from '@commercetools-frontend-extensions/operations'

const { upload, isUploading, progress, validationProgress } = useFileUpload({ 
  projectKey,
  useJobBasedFlow: isFeatureFlagEnabled
})

const abortController = new AbortController()

await upload({
  file: File,
  resourceType: 'product' | 'category' | ...,
  fileType?: 'csv' | 'json', // override derived file type (job-based flow only)
  settings?: {
    format?: 'CSV' | 'JSON',
    decimalSeparator?: '.' | ',',
    resourceType?: 'product-draft' | 'category' | ...,
    options?: {
      publishAllChanges?: boolean,
      unpublishAllChanges?: boolean
    }
  },
  autoProcess?: boolean, // job-based flow only, default: false
  skipValidationPolling?: boolean, // job-based flow only, default: false
  abortSignal: abortController.signal,
  onSuccess: (result) => {
    // result.containerKey - Import container key
    // result.summary - { total, valid, invalid, fields, ignoredFields, results }
    // result.jobId - Job ID (job-based flow only)
    // result.job - Full job object (job-based flow only)
  },
  onError: (error) => { /* ... */ },
  onProgress: (progress) => { /* 0-100 */ },
  onValidationProgress: (job) => { /* job-based flow only */ }
})

// To cancel:
abortController.abort()

useFetchImportOperations

Fetches import operations for a container with optional polling.

const { data, error, isLoading, refetch } = useFetchImportOperations({
  projectKey,
  importContainerKey,
  queryParams?: { limit, offset, ... },
  pollingInterval?: number,
  shouldContinuePolling?: (data) => boolean
})

useFetchImportSummaries

Fetches import summaries (containers) with optional polling.

const { data, error, isLoading, refetch } = useFetchImportSummaries({
  projectKey,
  queryParams?: { limit, offset, states, ... },
  pollingInterval?: number,
  shouldContinuePolling?: (data) => boolean
})

useFetchImportContainerDetails

Fetches details for a specific import container.

const { data, error, isLoading, refetch } = useFetchImportContainerDetails({
  projectKey,
  importContainerKey,
  pollingInterval?: number,
  shouldContinuePolling?: (data) => boolean
})

useFetchExportOperations

Fetches export operations with optional polling.

const { data, error, isLoading, refetch } = useFetchExportOperations({
  projectKey,
  queryParams?: { limit, offset, resourceTypes, ... },
  pollingInterval?: number,
  shouldContinuePolling?: (data) => boolean
})

useFetchFileImportJob

Polls a File Import Job for status updates.

const { data, error, isLoading, refetch } = useFetchFileImportJob({
  projectKey,
  importContainerKey,
  jobId,
  pollingInterval?: number,
  shouldContinuePolling?: (job) => boolean
})

Job states: queued → processing → validated → initialising → ready

useFetchFileImportJobRecords

Fetches records (errors or valid entries) from a File Import Job with pagination support. Keeps previous data visible while loading new pages.

const { data, error, isLoading, refetch } = useFetchFileImportJobRecords({
  projectKey,
  importContainerKey,
  jobId,
  limit?: number,
  offset?: number,
  isValid?: boolean,
  skip?: boolean
})

Parameters:

• projectKey: The commercetools project key
• importContainerKey: The import container key
• jobId: The file import job ID
• limit (optional): Number of records to fetch per page
• offset (optional): Offset for pagination
• isValid (optional): Filter by valid (true) or invalid (false) records
• skip (optional): Skip fetching (useful for conditional fetching)

Returns:

• data - { results, total, limit, offset, count } or null
• error - Error object if fetch failed
• isLoading - Whether fetch is in progress
• refetch - Function to manually trigger a refetch

Usage example (paginated error table):

const pagination = usePaginationState()
const offset = (pagination.page.value - 1) * pagination.perPage.value

const { data, isLoading } = useFetchFileImportJobRecords({
  projectKey,
  importContainerKey: containerKey,
  jobId,
  offset,
  limit: pagination.perPage.value,
  isValid: false, // Fetch only invalid records (errors)
})

Helper Functions

import {
  isImportJobQueued,
  isImportJobProcessing,
  isImportJobValidated,
  isImportJobInitializing,
  isImportJobReady,
  shouldContinuePollingForImportValidation
} from '@commercetools-frontend-extensions/operations'

Polling Example

const { data, isLoading } = useFetchImportOperations({
  projectKey,
  importContainerKey,
  pollingInterval: 5000,
  shouldContinuePolling: (data) => {
    return data?.results?.some(op => op.state === 'processing') ?? false
  }
})