@commercetools-frontend-extensions/operations 0.0.0-canary-20251209161906

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

@@ -0,0 +1,147 @@
+import type { ResourceTypeId } from '@commercetools/importapi-sdk'
+import { hasRequiredFields } from './shared'
+
+export type ExportOperationState =
+  | 'processing'
+  | 'completed'
+  | 'failed'
+  | 'queued'
+
+export type ResourceType = ResourceTypeId
+
+export type FileFormat = 'json' | 'csv'
+
+export type Separator = {
+  columns?: string
+  arrayValues?: string
+  decimal?: string
+}
+
+export type ExportOperation = {
+  id: string
+  fileName: string
+  createdAt: string
+  resourceType: ResourceType
+  state: ExportOperationState
+  completedPercentage: number
+  resourceCount: number
+  fileFormat: FileFormat
+  fields: string[]
+  locales: string[]
+  query?: string
+  filters?: {
+    filters: string[]
+    fullText?: {
+      text: string
+      locale: string
+    }
+  }
+  fillRows?: boolean
+  excelCompatible?: boolean
+  dryRun?: boolean
+  separator?: Separator
+}
+
+export interface PaginatedExportOperationResponse {
+  results: ExportOperation[]
+  limit: number
+  offset: number
+  total: number
+  count: number
+}
+
+export type DownloadFile = {
+  uri: string
+}
+
+export type ExportOperationQueryParams = {
+  limit: number
+  offset: number
+}
+
+export function assertPaginatedExportOperationResponse(
+  maybePaginatedExportOperationResponseOrExportOperationsResponse: unknown
+): asserts maybePaginatedExportOperationResponseOrExportOperationsResponse is PaginatedExportOperationResponse {
+  const requiredFields = ['results', 'total']
+  if (
+    hasRequiredFields(
+      maybePaginatedExportOperationResponseOrExportOperationsResponse,
+      requiredFields
+    )
+  )
+    return
+  throw new Error('Invalid response')
+}
+
+export function assertExportOperationsDownloadFileResponse(
+  maybeExportOperationDownloadFileResponse: unknown
+): asserts maybeExportOperationDownloadFileResponse is DownloadFile {
+  const requiredFields = ['uri']
+  if (
+    hasRequiredFields(maybeExportOperationDownloadFileResponse, requiredFields)
+  )
+    return
+  throw new Error('Invalid response')
+}
+
+export type QueryFilter = {
+  query?: Record<string, unknown>
+}
+
+export type SearchFilter = {
+  filters?: string[]
+  fullText?: {
+    text: string
+    locale: string
+  }
+}
+
+export interface ExportApiRequest {
+  projectKey: string
+  resourceType: string
+  fileName: string
+  fileFormat: string
+  fields: string[]
+  locales?: string[]
+  filters?: QueryFilter | SearchFilter
+  where?: string
+  fullText?: {
+    text: string
+    locale: string
+  }
+  fillRows?: boolean
+  excelCompatible?: boolean
+  separator?: Separator
+}
+
+export interface ExportApiSuccessResponse {
+  id: string
+  state: string
+  resourceType: string
+  resourceCount: number
+  createdAt: string
+}
+
+export interface ExportApiErrorResponse {
+  statusCode: number
+  error: string
+  errors: ValidationError[]
+  message: string
+}
+
+export type ValidationErrorCode =
+  | 'DuplicateFields'
+  | 'NotSupportedField'
+  | 'FieldDefinitionNotFound'
+  | '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

@@ -0,0 +1,81 @@
+import type { ResourceTypeId } from '@commercetools/importapi-sdk'
+
+export type FileUploadError = {
+  title: string
+  description: string
+}
+
+export type UploadFileErrorRow = {
+  id: string
+  row?: number
+  index?: number
+  code: string
+  field: string
+  validationMessage: string
+}
+
+export type RowError = {
+  code: string
+  message: string
+  field: string
+}
+
+export type RowErrorsResponse = {
+  row?: number
+  index?: number
+  errors: Array<RowError>
+}
+
+export type FileUploadResponse = {
+  results: Array<RowErrorsResponse>
+  invalid: number
+  valid: number
+  fileName: string
+  itemsCount: number
+  rowsCount: number
+  columnsCount: number
+  fields: Array<string>
+  ignoredFields: Array<string>
+}
+
+export interface FileUploadRequestParameters {
+  projectKey: string
+  importContainerKey: string
+  resourceType: ResourceTypeId
+  file: File
+  abortSignal?: AbortSignal
+  onSuccess: (data: FileUploadResponse) => void
+  onProgress: (progress: number) => void
+  onError: (error: Error) => void
+}
+
+export interface ProcessUploadedFileRequestParameters {
+  projectKey: string
+  importContainerKey: string
+  resourceType: ResourceTypeId
+  action?: 'delete' // Currently only 'delete' action is supported
+}
+
+export type ProcessFileResponse = {
+  message: string
+}
+
+export type MissingCsvFieldIdentifierError = {
+  code: string
+  message: string
+  rowValue: Record<string, unknown>
+  metadata: {
+    row: number
+  }
+}
+
+export type DecimalSeparator = '.' | ','
+
+export type DropAreaState =
+  | 'default'
+  | 'active-drag'
+  | 'ready-for-drop'
+  | 'file-dropped'
+  | 'disabled'
+  | 'invalid'
+  | 'is-parsing'

package/src/@types/import-container.ts

@@ -0,0 +1,104 @@
+import type {
+  ImportContainerPagedResponse,
+  ImportContainer,
+  ImportContainerDraft,
+} from '@commercetools/importapi-sdk'
+import { hasRequiredFields } from './shared'
+import { type DecimalSeparator } from './file-upload'
+import {
+  type ExtendedImportSummary,
+  type ImportSummary,
+} from './import-summary'
+import { type ImportStates } from './import-states'
+
+export function assertImportContainerPagedResponse(
+  maybeImportContainerPagedResponse: unknown
+): asserts maybeImportContainerPagedResponse is ImportContainerPagedResponse {
+  const requiredFields = ['count', 'results']
+  if (hasRequiredFields(maybeImportContainerPagedResponse, requiredFields))
+    return
+  throw new Error('Invalid response')
+}
+
+export function assertImportSummary(
+  maybeImportSummary: unknown
+): asserts maybeImportSummary is ExtendedImportSummary {
+  const requiredFields = ['states', 'total']
+  if (hasRequiredFields(maybeImportSummary, requiredFields)) return
+  throw new Error('Invalid response')
+}
+
+export function assertImportContainer(
+  maybeImportContainerResponse: unknown
+): asserts maybeImportContainerResponse is ImportContainer {
+  const requiredFields = ['key', 'version']
+  if (hasRequiredFields(maybeImportContainerResponse, requiredFields)) return
+  throw new Error('Invalid response')
+}
+
+export type CancelContainerResponse = {
+  message: string
+}
+
+export function assertCancelContainerResponse(
+  maybeCancelContainerResponse: unknown
+): asserts maybeCancelContainerResponse is CancelContainerResponse {
+  if (
+    typeof maybeCancelContainerResponse === 'object' &&
+    maybeCancelContainerResponse !== null
+  ) {
+    const responseData = maybeCancelContainerResponse as Record<string, unknown>
+    if (typeof responseData.message === 'string') {
+      return
+    }
+  }
+  throw new Error('Invalid response')
+}
+
+export type ImportContainerQueryParams = {
+  limit?: number
+  offset?: number
+  sort?: string
+  tags?: string
+}
+
+// Extended types to support settings that aren't in the base SDK yet
+export interface ExtendedImportContainer extends ImportContainer {
+  settings?: {
+    resourceType?: string
+    format?: string
+    decimalSeparator?: DecimalSeparator
+    options?: {
+      publishAllChanges?: boolean
+      unpublishAllChanges?: boolean
+    }
+  }
+  tags?: string[]
+}
+
+export interface ExtendedImportContainerDraft extends ImportContainerDraft {
+  settings?: {
+    resourceType?: string
+    format?: string
+    decimalSeparator?: DecimalSeparator
+    options?: {
+      publishAllChanges?: boolean
+      unpublishAllChanges?: boolean
+    }
+  }
+  tags?: string[]
+}
+
+export type ImportContainerDetails = {
+  importContainer: ExtendedImportContainer
+  importState: ImportStates
+  importSummary: ImportSummary
+  isFileUploadImport: boolean
+}
+
+export type ImportSummaries = {
+  results: Array<Promise<ImportContainerDetails>>
+  count: number
+  total: number
+  queryParams: ImportContainerQueryParams
+}

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

@@ -0,0 +1,31 @@
+import type {
+  ImportOperation,
+  ImportOperationPagedResponse,
+} from '@commercetools/importapi-sdk'
+import { hasRequiredFields } from './shared'
+
+export type ImportOperationQueryParams = {
+  limit?: number
+  offset?: number
+  state?: string | string[]
+}
+
+// TODO: Remove the temporarily extended ImportOperation when the SDK is updated
+export interface ExtendedImportOperation extends ImportOperation {
+  tags?: string[]
+}
+
+// TODO: Remove the temporarily extended ImportOperationPagedResponse when the SDK is updated
+export interface ExtendedImportOperationPagedResponse
+  extends ImportOperationPagedResponse {
+  results: ExtendedImportOperation[]
+}
+
+export function assertImportOperationPagedResponse(
+  maybeImportOperationPagedResponse: unknown
+): asserts maybeImportOperationPagedResponse is ExtendedImportOperationPagedResponse {
+  const requiredFields = ['count', 'total', 'results']
+  if (hasRequiredFields(maybeImportOperationPagedResponse, requiredFields))
+    return
+  throw new Error('Invalid response')
+}

package/src/@types/import-states.ts

@@ -0,0 +1,9 @@
+export enum ImportStates {
+  Processing = 'processing',
+  WaitForUnresolvedReferences = 'wait-for-unresolved-references',
+  PartiallyCompleted = 'partially-completed',
+  Failed = 'failed',
+  SuccessfullyCompleted = 'successfully-completed',
+  NoRunningImports = 'no-running-imports',
+  Canceled = 'canceled',
+}

package/src/@types/import-summary.ts

@@ -0,0 +1,22 @@
+import type {
+  OperationStates,
+  ImportSummary,
+} from '@commercetools/importapi-sdk'
+
+interface ExtendedOperationStates extends OperationStates {
+  /**
+   * The number of resources in the `canceled` state.
+   */
+  readonly canceled: number
+  /**
+   * The number of resources in the `deleted` state.
+   */
+  readonly deleted: number
+}
+
+export interface ExtendedImportSummary extends ImportSummary {
+  readonly states: ExtendedOperationStates
+}
+
+// Re-export as ImportSummary for convenience
+export { type ExtendedImportSummary as ImportSummary }

package/src/@types/index.ts

@@ -0,0 +1,11 @@
+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'
+export * from './import-summary'
+export * from './shared'

package/src/@types/shared.ts

@@ -0,0 +1,52 @@
+export function hasOwnProperty<X extends {}, Y extends PropertyKey>(
+  obj: X,
+  prop: Y
+): obj is X & Record<Y, unknown> {
+  return typeof obj === 'object' && obj !== null && obj.hasOwnProperty(prop)
+}
+
+export function hasRequiredFields(
+  maybeValidObject: unknown,
+  requiredFields: Array<string>
+): boolean {
+  return (
+    typeof maybeValidObject === 'object' &&
+    maybeValidObject !== null &&
+    requiredFields.every((property) =>
+      hasOwnProperty(maybeValidObject, property)
+    )
+  )
+}
+
+export function getMissingRequiredFields(
+  maybeValidObject: unknown,
+  requiredFields: Array<string>
+): string[] | false {
+  return (
+    typeof maybeValidObject === 'object' &&
+    maybeValidObject !== null &&
+    requiredFields.filter((property) => !(property in maybeValidObject))
+  )
+}
+
+export function isError(maybeError: unknown): maybeError is Error {
+  if (maybeError instanceof Error) return true
+  return false
+}
+
+export function isAbortError(error: unknown): error is DOMException {
+  return error instanceof DOMException && error.name === 'AbortError'
+}
+
+export function isResourceType<T extends string>(
+  maybeResourceType: unknown
+): maybeResourceType is T {
+  return typeof maybeResourceType === 'string'
+}
+
+export function assertResourceType<T extends string>(
+  maybeResourceType: unknown
+): asserts maybeResourceType is T {
+  if (typeof maybeResourceType === 'string') return
+  throw new Error(`Invalid value: ${maybeResourceType}`)
+}