@commercetools-frontend-extensions/operations 0.0.0 → 3.0.0

package/src/@hooks/use-file-upload.ts

@@ -0,0 +1,223 @@
+import React from 'react'
+import type { ResourceTypeId } from '@commercetools/importapi-sdk'
+import { useImportContainerUpload } from './use-import-container-upload'
+import { useFileImportJobUpload } from './use-file-import-job-upload'
+import { getFileImportJobRecords, deleteImportContainer } from '../@api'
+import { HttpError, PollingAbortedError } from '../@errors'
+import { pollJobUntilValidated } from '../@utils'
+import type {
+  ExtendedImportContainerDraft,
+  FileUploadResult,
+  FileImportJob,
+} from '../@types'
+
+export type ValidationProgress = {
+  processed: number
+  isValidating: boolean
+}
+
+export type FileUploadConfig = {
+  file: File
+  resourceType: ResourceTypeId
+  settings?: ExtendedImportContainerDraft['settings']
+  onSuccess: (result: FileUploadResult) => void
+  onError?: (error: unknown) => void
+  onProgress?: (progress: number) => void
+  onValidationProgress?: (job: FileImportJob) => void
+  abortSignal?: AbortSignal
+}
+
+export type FileUploadOptions = {
+  projectKey: string
+  useJobBasedFlow?: boolean
+  pollingInterval?: number
+  maxPollingAttempts?: number
+}
+
+const safeDeleteContainer = async ({
+  projectKey,
+  containerKey,
+}: {
+  projectKey: string
+  containerKey: string
+}) => {
+  try {
+    await deleteImportContainer({
+      projectKey,
+      importContainerKey: containerKey,
+    })
+  } catch {}
+}
+
+export const useFileUpload = ({
+  projectKey,
+  useJobBasedFlow = false,
+  pollingInterval = 5000,
+  maxPollingAttempts = 120,
+}: FileUploadOptions) => {
+  const [isUploading, setIsUploading] = React.useState(false)
+  const [progress, setProgress] = React.useState(0)
+  const [validationProgress, setValidationProgress] =
+    React.useState<ValidationProgress>({
+      processed: 0,
+      isValidating: false,
+    })
+
+  const containerUpload = useImportContainerUpload({ projectKey })
+  const jobUpload = useFileImportJobUpload({ projectKey })
+
+  const resetState = React.useCallback(() => {
+    setIsUploading(false)
+    setProgress(0)
+    setValidationProgress({ processed: 0, isValidating: false })
+  }, [])
+
+  const upload = React.useCallback(
+    async (config: FileUploadConfig) => {
+      setIsUploading(true)
+      setProgress(0)
+
+      try {
+        if (useJobBasedFlow) {
+          await jobUpload.upload({
+            file: config.file,
+            resourceType: config.resourceType,
+            settings: config.settings,
+            abortSignal: config.abortSignal,
+            onSuccess: async (jobId, containerKey) => {
+              try {
+                setValidationProgress({ processed: 0, isValidating: true })
+
+                const validatedJob = await pollJobUntilValidated({
+                  projectKey,
+                  jobId,
+                  importContainerKey: containerKey,
+                  pollingInterval,
+                  maxAttempts: maxPollingAttempts,
+                  abortSignal: config.abortSignal,
+                  onJobUpdate: (job) => {
+                    const processed = job.summary?.total ?? 0
+                    setValidationProgress({ processed, isValidating: true })
+                    config.onValidationProgress?.(job)
+                  },
+                })
+
+                // Handle rejected job with jobError for the new flow (like MissingCsvFieldIdentifier error)
+                // We wrap it in HttpError to reuse existing error handling (for the old flow) in consumers until BE supports this error type
+                if (validatedJob.jobError) {
+                  throw new HttpError(
+                    400,
+                    validatedJob.jobError.message,
+                    validatedJob.jobError
+                  )
+                }
+
+                let results: FileUploadResult['summary']['results'] = []
+                if (validatedJob.summary.invalid > 0) {
+                  const recordsResponse = await getFileImportJobRecords({
+                    projectKey,
+                    importContainerKey: containerKey,
+                    jobId,
+                    limit: 500,
+                    isValid: false,
+                  })
+                  results = recordsResponse.results
+                  await safeDeleteContainer({ projectKey, containerKey })
+                }
+
+                const result: FileUploadResult = {
+                  containerKey,
+                  summary: {
+                    ...validatedJob.summary,
+                    results,
+                  },
+                  jobId,
+                  job: validatedJob,
+                }
+
+                setIsUploading(false)
+                setValidationProgress({ processed: 0, isValidating: false })
+                config.onSuccess(result)
+              } catch (error) {
+                await safeDeleteContainer({ projectKey, containerKey })
+                resetState()
+
+                if (!(error instanceof PollingAbortedError)) {
+                  config.onError?.(error)
+                }
+              }
+            },
+            onProgress: (prog) => {
+              setProgress(prog)
+              config.onProgress?.(prog)
+            },
+            onError: (error) => {
+              resetState()
+              config.onError?.(error)
+            },
+          })
+        } else {
+          await containerUpload.upload({
+            file: config.file,
+            resourceType: config.resourceType,
+            settings: config.settings,
+            abortSignal: config.abortSignal,
+            onSuccess: async (fileUploadResponse, containerKey) => {
+              if (config.abortSignal?.aborted) {
+                await safeDeleteContainer({ projectKey, containerKey })
+                resetState()
+                return
+              }
+
+              if (fileUploadResponse.invalid > 0) {
+                await safeDeleteContainer({ projectKey, containerKey })
+              }
+
+              const result: FileUploadResult = {
+                containerKey,
+                summary: {
+                  total: fileUploadResponse.itemsCount,
+                  valid: fileUploadResponse.valid,
+                  invalid: fileUploadResponse.invalid,
+                  fieldsCount: fileUploadResponse.columnsCount,
+                  fields: fileUploadResponse.fields || [],
+                  ignoredFields: fileUploadResponse.ignoredFields || [],
+                  results: fileUploadResponse.results || [],
+                },
+              }
+
+              setIsUploading(false)
+              config.onSuccess(result)
+            },
+            onProgress: (prog) => {
+              setProgress(prog)
+              config.onProgress?.(prog)
+            },
+            onError: (error) => {
+              resetState()
+              config.onError?.(error)
+            },
+          })
+        }
+      } catch (error) {
+        resetState()
+        config.onError?.(error)
+      }
+    },
+    [
+      projectKey,
+      useJobBasedFlow,
+      pollingInterval,
+      maxPollingAttempts,
+      containerUpload,
+      jobUpload,
+    ]
+  )
+
+  return {
+    upload,
+    isUploading,
+    progress,
+    validationProgress,
+  }
+}

package/src/@hooks/use-import-container-upload.spec.ts

@@ -42,8 +42,8 @@ describe('useImportContainerUpload', () => {
     itemsCount: 10,
     rowsCount: 10,
     columnsCount: 2,
-    columns: ['key', 'value'],
-    ignoredColumns: [],
+    fields: ['key', 'value'],
+    ignoredFields: [],
   }
 
   beforeEach(() => {
@@ -153,6 +153,7 @@ describe('useImportContainerUpload', () => {
   })
 
   it('should delete container if upload throws before starting', async () => {
+    const onError = jest.fn()
     const error = new Error('Container creation failed')
     mockCreateImportContainerForFileUpload.mockRejectedValue(error)
 
@@ -160,20 +161,22 @@ describe('useImportContainerUpload', () => {
       useImportContainerUpload({ projectKey })
     )
 
-    await expect(
-      act(async () => {
-        await result.current.upload({
-          file: mockFile,
-          resourceType: 'product',
-          onSuccess: jest.fn(),
-        })
+    await act(async () => {
+      await result.current.upload({
+        file: mockFile,
+        resourceType: 'product',
+        onSuccess: jest.fn(),
+        onError,
       })
-    ).rejects.toThrow(error)
+    })
 
-    expect(mockDeleteImportContainer).toHaveBeenCalledWith({
-      projectKey,
-      importContainerKey,
+    await waitFor(() => {
+      expect(mockDeleteImportContainer).toHaveBeenCalledWith({
+        projectKey,
+        importContainerKey,
+      })
     })
+    expect(onError).toHaveBeenCalledWith(error)
   })
 
   it('should update progress during upload', async () => {

package/src/@hooks/use-import-container-upload.ts

@@ -20,6 +20,7 @@ export type UseImportContainerUploadConfig = {
   onSuccess: (response: FileUploadResponse, importContainerKey: string) => void
   onError?: (error: unknown) => void
   onProgress?: (progress: number) => void
+  abortSignal?: AbortSignal
 }
 
 export const useImportContainerUpload = ({
@@ -38,7 +39,8 @@ export const useImportContainerUpload = ({
     onSuccess,
     onError,
     onProgress,
-  }: UseImportContainerUploadConfig): Promise<XMLHttpRequest> => {
+    abortSignal,
+  }: UseImportContainerUploadConfig): Promise<XMLHttpRequest | undefined> => {
     if (!projectKey) {
       throw new ProjectKeyNotAvailableError()
     }
@@ -66,6 +68,7 @@ export const useImportContainerUpload = ({
         importContainerKey,
         resourceType,
         file,
+        abortSignal,
         onSuccess: (response) => {
           setIsUploading(false)
           setProgress(100)
@@ -107,7 +110,8 @@ export const useImportContainerUpload = ({
 
       setIsUploading(false)
       setProgress(0)
-      throw error
+      onError?.(error)
+      return undefined
     }
   }
 

package/src/@types/export-operation.ts

@@ -136,9 +136,12 @@ export type ValidationErrorCode =
   | 'AttributeDefinitionNotFound'
   | 'LocalizedFieldWithoutLocale'
   | 'IncompleteField'
+  | 'AttributeLevelMismatch'
 
 export type ValidationError = {
   code: ValidationErrorCode
   message: string
   field?: string
+  requestedLevel?: string
+  actualLevel?: string
 }

package/src/@types/file-import-job.ts

@@ -0,0 +1,165 @@
+import { hasRequiredFields } from './shared'
+
+export type FileImportJobState =
+  | 'queued'
+  | 'processing'
+  | 'validated'
+  | 'initialising'
+  | 'ready'
+  | 'rejected'
+
+export interface FileImportJobSummary {
+  total: number
+  invalid: number
+  valid: number
+  fieldsCount: number
+  fields: string[]
+  ignoredFields: string[]
+}
+
+export interface FileImportJobValidationError {
+  code: string
+  message: string
+  rowValue?: Record<string, string>
+  metadata?: {
+    row?: number
+  }
+}
+
+export interface FileImportJob {
+  id: string
+  fileName: string
+  importContainerKey: string
+  state: FileImportJobState
+  summary: FileImportJobSummary
+  jobError?: FileImportJobValidationError | null
+}
+
+export interface CreateFileImportJobWithStreamPayload {
+  fileType: 'csv' | 'json'
+  fileName: string
+  file: File
+}
+
+export interface CreateFileImportJobWithReferencePayload {
+  payloadType: 'fileReference'
+  fileName: string
+  fileUrl: string
+}
+
+export type CreateFileImportJobPayload =
+  | CreateFileImportJobWithStreamPayload
+  | CreateFileImportJobWithReferencePayload
+
+export interface CreateFileImportJobParameters {
+  projectKey: string
+  resourceType: string
+  importContainerKey: string
+  payload: CreateFileImportJobPayload
+  onProgress?: (progress: number) => void
+  abortSignal?: AbortSignal
+}
+
+export interface GetFileImportJobParameters {
+  projectKey: string
+  importContainerKey: string
+  jobId: string
+}
+
+export interface FileImportJobError {
+  code: string
+  message: string
+  field: string
+}
+
+export interface FileImportJobErrorRecord {
+  index: number
+  errors: FileImportJobError[]
+}
+
+export interface FileImportJobRecordsResponse {
+  results: FileImportJobErrorRecord[]
+  total: number
+  limit: number
+  offset: number
+  count: number
+}
+
+export interface GetFileImportJobRecordsParameters {
+  projectKey: string
+  importContainerKey: string
+  jobId: string
+  limit?: number
+  offset?: number
+  isValid?: boolean
+}
+
+export interface ProcessFileImportJobParameters {
+  projectKey: string
+  resourceType: string
+  importContainerKey: string
+  jobId: string
+  action?: 'delete'
+}
+
+export interface ProcessFileImportJobResponse {
+  message: string
+}
+
+export interface DeleteFileImportJobParameters {
+  projectKey: string
+  importContainerKey: string
+  jobId: string
+}
+
+export interface ListFileImportJobsParameters {
+  projectKey: string
+  importContainerKey: string
+  limit?: number
+  offset?: number
+}
+
+export type ListFileImportJobsResponse = FileImportJob[]
+
+export function assertFileImportJob(
+  maybeJob: unknown
+): asserts maybeJob is FileImportJob {
+  const requiredFields = ['id', 'fileName', 'importContainerKey', 'state']
+  if (hasRequiredFields(maybeJob, requiredFields)) return
+  throw new Error('Invalid File Import Job response')
+}
+
+export function assertFileImportJobRecordsResponse(
+  maybeRecords: unknown
+): asserts maybeRecords is FileImportJobRecordsResponse {
+  const requiredFields = ['results', 'total', 'limit', 'offset', 'count']
+  if (!hasRequiredFields(maybeRecords, requiredFields)) {
+    throw new Error(
+      'Invalid File Import Job records response: missing required fields'
+    )
+  }
+}
+
+export function assertProcessFileImportJobResponse(
+  maybeResponse: unknown
+): asserts maybeResponse is ProcessFileImportJobResponse {
+  const requiredFields = ['message']
+  if (hasRequiredFields(maybeResponse, requiredFields)) return
+  throw new Error('Invalid Process File Import Job response')
+}
+
+export function assertListFileImportJobsResponse(
+  maybeResponse: unknown
+): asserts maybeResponse is ListFileImportJobsResponse {
+  if (!Array.isArray(maybeResponse)) {
+    throw new Error('Invalid List File Import Jobs response: expected an array')
+  }
+  if (maybeResponse.length > 0) {
+    const requiredFields = ['id', 'fileName', 'importContainerKey', 'state']
+    if (!hasRequiredFields(maybeResponse[0], requiredFields)) {
+      throw new Error(
+        'Invalid List File Import Jobs response: missing required fields'
+      )
+    }
+  }
+}

package/src/@types/file-upload-result.ts

@@ -0,0 +1,23 @@
+import type { FileImportJob } from './file-import-job'
+import type { RowErrorsResponse } from './file-upload'
+
+export interface FileUploadResult {
+  containerKey: string
+  summary: {
+    total: number
+    valid: number
+    invalid: number
+    fieldsCount: number
+    fields: string[]
+    ignoredFields: string[]
+    /**
+     * Validation errors. Format is compatible between old and new flows:
+     * - Old flow: { row?: number, index?: number, errors: RowError[] }
+     * - New flow: { index: number, errors: FileImportJobError[] }
+     */
+    results: Array<RowErrorsResponse>
+  }
+  // new job based flow-specific fields
+  jobId?: string
+  job?: FileImportJob
+}

package/src/@types/file-upload.ts

@@ -34,8 +34,8 @@ export type FileUploadResponse = {
   itemsCount: number
   rowsCount: number
   columnsCount: number
-  columns: Array<string>
-  ignoredColumns: Array<string>
+  fields: Array<string>
+  ignoredFields: Array<string>
 }
 
 export interface FileUploadRequestParameters {

package/src/@types/index.ts

@@ -2,6 +2,8 @@ export * from './api'
 export * from './basic-error-data-type'
 export * from './export-operation'
 export * from './file-upload'
+export * from './file-upload-result'
+export * from './file-import-job'
 export * from './import-container'
 export * from './import-operation'
 export * from './import-states'

package/src/@utils/error-mapping.ts

@@ -5,6 +5,7 @@ export function getFileUploadErrorsCount(
   return errors.reduce((acc, curr) => (acc += curr.errors.length), 0)
 }
 
+// TODO: After fully migrating to new flow, remove `row` and only use `index`
 export function mapUploadFileErrorsResponseToUploadFileErrorRows(
   uploadFileErrorsResponse?: Array<{
     row?: number
@@ -22,18 +23,18 @@ export function mapUploadFileErrorsResponseToUploadFileErrorRows(
   if (!uploadFileErrorsResponse || !Array.isArray(uploadFileErrorsResponse))
     return []
   let idCounter = 1
-  return uploadFileErrorsResponse.flatMap((rowErrorsResponse) =>
-    rowErrorsResponse.errors.map((rowError) => ({
+  return uploadFileErrorsResponse.flatMap((rowErrorsResponse) => {
+    // TODO: use `row` if available, otherwise fall back to `index`
+    // Old flow uses `row`, new flow uses `index`
+    const rowNumber = rowErrorsResponse.row ?? rowErrorsResponse.index
+
+    return rowErrorsResponse.errors.map((rowError) => ({
       id: String(idCounter++),
-      ...(rowErrorsResponse.row !== undefined
-        ? { row: rowErrorsResponse.row }
-        : {}),
-      ...(rowErrorsResponse.index !== undefined
-        ? { index: rowErrorsResponse.index }
-        : {}),
+      row: rowNumber,
+      index: rowNumber,
       field: rowError.field,
       code: rowError.code,
       validationMessage: rowError.message,
     }))
-  )
+  })
 }