@commercetools-frontend-extensions/operations 2.0.1 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @commercetools-frontend-extensions/operations
 
+## 3.0.0
+
+### Major Changes
+
+- [#1646](https://github.com/commercetools/merchant-center-operations/pull/1646) [`c1c381d`](https://github.com/commercetools/merchant-center-operations/commit/c1c381da4aa5c47c6fcc63940f164defe08170bd) Thanks [@yassinejebli](https://github.com/yassinejebli)! - feat: introduce the new Import job flow
+
 ## 2.0.1
 
 ### Patch Changes

package/README.md

@@ -4,73 +4,86 @@ Shared functionality for import/export operations across multiple frontend appli
 
 ## Hooks
 
-### `useImportContainerUpload`
+### `useFileUpload`
 
-Handles file upload to import containers with automatic cleanup on errors.
+A unified hook for file uploads that handles both the old flow (import container) and new flow (file import job).
 
 ```typescript
-const { upload, abort, isUploading, progress } = useImportContainerUpload({
-  projectKey: string
+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: `120`
 
 **Returns:**
-- `upload`: Function to start file upload
-- `abort`: Function to cancel ongoing upload
-- `isUploading`: Boolean indicating upload state
-- `progress`: Upload progress (0-100)
+- `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)
 
 **Usage:**
 ```typescript
-const projectKey = useApplicationContext((context) => context.project?.key)
-const { upload, isUploading, progress } = useImportContainerUpload({ 
-  projectKey: projectKey! 
+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' | ...,
   settings?: {
     format?: 'CSV' | 'JSON',
     decimalSeparator?: '.' | ',',
-    resourceType?: string,  // example: 'product-draft' for products
+    resourceType?: 'product-draft' | 'category' | ...,
     options?: {
-      publishAllChanges?: boolean,      // product-specific
-      unpublishAllChanges?: boolean     // product-specific
+      publishAllChanges?: boolean,
+      unpublishAllChanges?: boolean
     }
   },
-  onSuccess: (response, containerKey) => { /* ... */ },
+  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) => { /* ... */ }
+  onProgress: (progress) => { /* 0-100 */ },
+  onValidationProgress: (job) => { /* job-based flow only */ }
 })
+
+// To cancel:
+abortController.abort()
 ```
 
 ---
 
 ### `useFetchImportOperations`
 
-Fetches import operations for a specific container with optional polling.
+Fetches import operations for a container with optional polling.
 
 ```typescript
-const { data, error, isLoading, refetch, lastFetchTime } = useFetchImportOperations({
-  projectKey: string,
-  importContainerKey: string,
-  queryParams?: ImportOperationQueryParams,
+const { data, error, isLoading, refetch } = useFetchImportOperations({
+  projectKey,
+  importContainerKey,
+  queryParams?: { limit, offset, ... },
   pollingInterval?: number,
   shouldContinuePolling?: (data) => boolean
 })
 ```
 
-**Parameters:**
-- `projectKey` (required): The commercetools project key
-- `importContainerKey` (required): The import container key
-- `queryParams`: Optional query parameters (limit, offset, etc.)
-- `pollingInterval`: Polling interval in milliseconds
-- `shouldContinuePolling`: Function to determine if polling should continue
-
 ---
 
 ### `useFetchImportSummaries`
@@ -78,41 +91,29 @@ const { data, error, isLoading, refetch, lastFetchTime } = useFetchImportOperati
 Fetches import summaries (containers) with optional polling.
 
 ```typescript
-const { data, error, isLoading, refetch, lastFetchTime } = useFetchImportSummaries({
-  projectKey: string,
-  queryParams?: ImportContainerQueryParams,
+const { data, error, isLoading, refetch } = useFetchImportSummaries({
+  projectKey,
+  queryParams?: { limit, offset, states, ... },
   pollingInterval?: number,
   shouldContinuePolling?: (data) => boolean
 })
 ```
 
-**Parameters:**
-- `projectKey` (required): The commercetools project key
-- `queryParams`: Optional query parameters (limit, offset, states, etc.)
-- `pollingInterval`: Polling interval in milliseconds
-- `shouldContinuePolling`: Function to determine if polling should continue
-
 ---
 
 ### `useFetchImportContainerDetails`
 
-Fetches details for a specific import container with optional polling.
+Fetches details for a specific import container.
 
 ```typescript
-const { data, error, isLoading, refetch, lastFetchTime } = useFetchImportContainerDetails({
-  projectKey: string,
-  importContainerKey: string,
+const { data, error, isLoading, refetch } = useFetchImportContainerDetails({
+  projectKey,
+  importContainerKey,
   pollingInterval?: number,
   shouldContinuePolling?: (data) => boolean
 })
 ```
 
-**Parameters:**
-- `projectKey` (required): The commercetools project key
-- `importContainerKey` (required): The import container key
-- `pollingInterval`: Polling interval in milliseconds
-- `shouldContinuePolling`: Function to determine if polling should continue
-
 ---
 
 ### `useFetchExportOperations`
@@ -120,50 +121,58 @@ const { data, error, isLoading, refetch, lastFetchTime } = useFetchImportContain
 Fetches export operations with optional polling.
 
 ```typescript
-const { data, error, isLoading, refetch, lastFetchTime } = useFetchExportOperations({
-  projectKey: string,
-  queryParams?: ExportOperationQueryParams,
+const { data, error, isLoading, refetch } = useFetchExportOperations({
+  projectKey,
+  queryParams?: { limit, offset, resourceTypes, ... },
   pollingInterval?: number,
   shouldContinuePolling?: (data) => boolean
 })
 ```
 
-**Parameters:**
-- `projectKey` (required): The commercetools project key
-- `queryParams`: Optional query parameters (limit, offset, resourceTypes, etc.)
-- `pollingInterval`: Polling interval in milliseconds
-- `shouldContinuePolling`: Function to determine if polling should continue
-
 ---
 
-## Notes
+### `useFetchFileImportJob`
 
-- **All hooks require `projectKey`** to be passed explicitly (retrieved from `useApplicationContext`)
-- **Polling is opt-in** via `pollingInterval` parameter
-- **Standard return structure**: All fetch hooks return `{ data, error, isLoading, refetch, lastFetchTime }`
-- **Automatic cleanup**: `useImportContainerUpload` automatically cleans up containers on upload errors
-- **File upload limits**: The package exports backend-recommended limits enforced in frontend validation:
-  - `MAX_FILE_SIZE_MB` (35 MB)
-  - `MAX_ROW_COUNT` (80,000)
-- **Internal use only**: This package also exports additional components, utilities, types, and API functions that are intended for internal use within the operations repository (operations app and frontend extensions). Only the hooks documented above are considered stable public API for external consumption.
+Polls a File Import Job for status updates.
 
----
+```typescript
+const { data, error, isLoading, refetch } = useFetchFileImportJob({
+  projectKey,
+  importContainerKey,
+  jobId,
+  pollingInterval?: number,
+  shouldContinuePolling?: (job) => boolean
+})
+```
 
-## Common patterns
+**Job states:** `queued` → `processing` → `validated` → `initialising` → `ready`
 
-### Polling example
+---
+
+## Helper Functions
 
 ```typescript
-const POLL_INTERVAL = 5000 // 5 seconds
+import {
+  isImportJobQueued,
+  isImportJobProcessing,
+  isImportJobValidated,
+  isImportJobInitializing,
+  isImportJobReady,
+  shouldContinuePollingForImportValidation
+} from '@commercetools-frontend-extensions/operations'
+```
 
+---
+
+## Polling Example
+
+```typescript
 const { data, isLoading } = useFetchImportOperations({
   projectKey,
   importContainerKey,
-  pollingInterval: POLL_INTERVAL,
+  pollingInterval: 5000,
   shouldContinuePolling: (data) => {
-    // Stop polling when all operations are completed
     return data?.results?.some(op => op.state === 'processing') ?? false
   }
 })
 ```
-