refactor version validation to allow RCs and default to 2026-01 for bulk operations

Author: nickwesselman

packages/app/src/cli/services/bulk-operations/bulk-operation-status.test.ts

@@ -4,16 +4,25 @@ import {
   normalizeBulkOperationId,
   extractBulkOperationId,
 } from './bulk-operation-status.js'
+import {BULK_OPERATIONS_MIN_API_VERSION} from './constants.js'
 import {GetBulkOperationByIdQuery} from '../../api/graphql/bulk-operations/generated/get-bulk-operation-by-id.js'
 import {OrganizationApp, Organization, OrganizationSource} from '../../models/organization.js'
 import {ListBulkOperationsQuery} from '../../api/graphql/bulk-operations/generated/list-bulk-operations.js'
+import {resolveApiVersion} from '../graphql/common.js'
 import {afterEach, beforeEach, describe, expect, test, vi} from 'vitest'
 import {ensureAuthenticatedAdminAsApp} from '@shopify/cli-kit/node/session'
 import {adminRequestDoc} from '@shopify/cli-kit/node/api/admin'
 import {mockAndCaptureOutput} from '@shopify/cli-kit/node/testing/output'
 
 vi.mock('@shopify/cli-kit/node/session')
 vi.mock('@shopify/cli-kit/node/api/admin')
+vi.mock('../graphql/common.js', async () => {
+  const actual = await vi.importActual('../graphql/common.js')
+  return {
+    ...actual,
+    resolveApiVersion: vi.fn(),
+  }
+})
 
 const storeFqdn = 'test-store.myshopify.com'
 const operationId = 'gid://shopify/BulkOperation/123'
@@ -35,6 +44,7 @@ const remoteApp = {
 
 beforeEach(() => {
   vi.mocked(ensureAuthenticatedAdminAsApp).mockResolvedValue({token: 'test-token', storeFqdn})
+  vi.mocked(resolveApiVersion).mockResolvedValue('2026-01')
 })
 
 afterEach(() => {
@@ -169,6 +179,18 @@ describe('getBulkOperationStatus', () => {
     expect(output.info()).toContain('Bulk operation canceled.')
   })
 
+  test('calls resolveApiVersion with minimum API version', async () => {
+    vi.mocked(adminRequestDoc).mockResolvedValue(mockBulkOperation({status: 'RUNNING'}))
+
+    await getBulkOperationStatus({organization: mockOrganization, storeFqdn, operationId, remoteApp})
+
+    expect(resolveApiVersion).toHaveBeenCalledWith(
+      {token: 'test-token', storeFqdn},
+      undefined,
+      BULK_OPERATIONS_MIN_API_VERSION,
+    )
+  })
+
   describe('time formatting', () => {
     test('uses "Started" for running operations', async () => {
       vi.mocked(adminRequestDoc).mockResolvedValue(mockBulkOperation({status: 'RUNNING'}))
@@ -328,4 +350,16 @@ describe('listBulkOperations', () => {
     expect(output.info()).toContain('Listing bulk operations.')
     expect(output.info()).toContain('No bulk operations found in the last 7 days.')
   })
+
+  test('calls resolveApiVersion with minimum API version', async () => {
+    vi.mocked(adminRequestDoc).mockResolvedValue(mockBulkOperationsList([]))
+
+    await listBulkOperations({organization: mockOrganization, storeFqdn, remoteApp})
+
+    expect(resolveApiVersion).toHaveBeenCalledWith(
+      {token: 'test-token', storeFqdn},
+      undefined,
+      BULK_OPERATIONS_MIN_API_VERSION,
+    )
+  })
 })

packages/app/src/cli/services/bulk-operations/bulk-operation-status.ts

@@ -1,10 +1,11 @@
 import {BulkOperation} from './watch-bulk-operation.js'
 import {formatBulkOperationStatus} from './format-bulk-operation-status.js'
+import {BULK_OPERATIONS_MIN_API_VERSION} from './constants.js'
 import {
   GetBulkOperationById,
   GetBulkOperationByIdQuery,
 } from '../../api/graphql/bulk-operations/generated/get-bulk-operation-by-id.js'
-import {formatOperationInfo} from '../graphql/common.js'
+import {formatOperationInfo, resolveApiVersion} from '../graphql/common.js'
 import {OrganizationApp, Organization} from '../../models/organization.js'
 import {
   ListBulkOperations,
@@ -19,8 +20,6 @@ import {timeAgo, formatDate} from '@shopify/cli-kit/common/string'
 import {BugError} from '@shopify/cli-kit/node/error'
 import colors from '@shopify/cli-kit/node/colors'
 
-const API_VERSION = '2026-01'
-
 export function normalizeBulkOperationId(id: string): string {
   // If already a GID, return as-is
   if (id.startsWith('gid://')) {
@@ -63,7 +62,7 @@ export async function getBulkOperationStatus(options: GetBulkOperationStatusOpti
     body: [
       {
         list: {
-          items: formatOperationInfo({organization, remoteApp, storeFqdn, showVersion: false}),
+          items: formatOperationInfo({organization, remoteApp, storeFqdn}),
         },
       },
     ],
@@ -78,7 +77,7 @@ export async function getBulkOperationStatus(options: GetBulkOperationStatusOpti
     query: GetBulkOperationById,
     session: adminSession,
     variables: {id: operationId},
-    version: API_VERSION,
+    version: await resolveApiVersion(adminSession, undefined, BULK_OPERATIONS_MIN_API_VERSION),
   })
 
   if (response.bulkOperation) {
@@ -99,7 +98,7 @@ export async function listBulkOperations(options: ListBulkOperationsOptions): Pr
     body: [
       {
         list: {
-          items: formatOperationInfo({organization, remoteApp, storeFqdn, showVersion: false}),
+          items: formatOperationInfo({organization, remoteApp, storeFqdn}),
         },
       },
     ],
@@ -121,7 +120,7 @@ export async function listBulkOperations(options: ListBulkOperationsOptions): Pr
       sortKey: 'CREATED_AT',
       reverse: true,
     },
-    version: API_VERSION,
+    version: await resolveApiVersion(adminSession, undefined, BULK_OPERATIONS_MIN_API_VERSION),
   })
 
   const operations = response.bulkOperations.nodes.map((operation) => ({

packages/app/src/cli/services/bulk-operations/constants.ts

@@ -0,0 +1,5 @@
+/**
+ * Minimum API version for bulk operations.
+ * This ensures bulk operation features work correctly across all operations.
+ */
+export const BULK_OPERATIONS_MIN_API_VERSION = '2026-01'

packages/app/src/cli/services/bulk-operations/execute-bulk-operation.test.ts

@@ -3,7 +3,7 @@ import {runBulkOperationQuery} from './run-query.js'
 import {runBulkOperationMutation} from './run-mutation.js'
 import {watchBulkOperation, shortBulkOperationPoll} from './watch-bulk-operation.js'
 import {downloadBulkOperationResults} from './download-bulk-operation-results.js'
-import {validateApiVersion} from '../graphql/common.js'
+import {resolveApiVersion} from '../graphql/common.js'
 import {BulkOperationRunQueryMutation} from '../../api/graphql/bulk-operations/generated/bulk-operation-run-query.js'
 import {BulkOperationRunMutationMutation} from '../../api/graphql/bulk-operations/generated/bulk-operation-run-mutation.js'
 import {OrganizationApp, OrganizationSource} from '../../models/organization.js'
@@ -22,7 +22,7 @@ vi.mock('../graphql/common.js', async () => {
   const actual = await vi.importActual('../graphql/common.js')
   return {
     ...actual,
-    validateApiVersion: vi.fn(),
+    resolveApiVersion: vi.fn(),
   }
 })
 vi.mock('@shopify/cli-kit/node/ui')
@@ -68,6 +68,7 @@ describe('executeBulkOperation', () => {
   beforeEach(() => {
     vi.mocked(ensureAuthenticatedAdminAsApp).mockResolvedValue(mockAdminSession)
     vi.mocked(shortBulkOperationPoll).mockResolvedValue(createdBulkOperation)
+    vi.mocked(resolveApiVersion).mockResolvedValue('2026-01')
   })
 
   afterEach(() => {
@@ -92,6 +93,7 @@ describe('executeBulkOperation', () => {
     expect(runBulkOperationQuery).toHaveBeenCalledWith({
       adminSession: mockAdminSession,
       query,
+      version: '2026-01',
     })
     expect(runBulkOperationMutation).not.toHaveBeenCalled()
   })
@@ -114,6 +116,7 @@ describe('executeBulkOperation', () => {
     expect(runBulkOperationQuery).toHaveBeenCalledWith({
       adminSession: mockAdminSession,
       query,
+      version: '2026-01',
     })
     expect(runBulkOperationMutation).not.toHaveBeenCalled()
   })
@@ -137,6 +140,7 @@ describe('executeBulkOperation', () => {
       adminSession: mockAdminSession,
       query: mutation,
       variablesJsonl: undefined,
+      version: '2026-01',
     })
     expect(runBulkOperationQuery).not.toHaveBeenCalled()
   })
@@ -162,6 +166,7 @@ describe('executeBulkOperation', () => {
       adminSession: mockAdminSession,
       query: mutation,
       variablesJsonl: '{"input":{"id":"gid://shopify/Product/123","tags":["test"]}}',
+      version: '2026-01',
     })
   })
 
@@ -562,51 +567,6 @@ describe('executeBulkOperation', () => {
     expect(renderSuccess).not.toHaveBeenCalled()
   })
 
-  test('validates API version when provided', async () => {
-    const query = '{ products { edges { node { id } } } }'
-    const version = '2025-01'
-    const mockResponse: BulkOperationRunQueryMutation['bulkOperationRunQuery'] = {
-      bulkOperation: createdBulkOperation,
-      userErrors: [],
-    }
-    vi.mocked(runBulkOperationQuery).mockResolvedValue(mockResponse)
-    vi.mocked(validateApiVersion).mockResolvedValue()
-
-    await executeBulkOperation({
-      organization: mockOrganization,
-      remoteApp: mockRemoteApp,
-      storeFqdn,
-      query,
-      version,
-    })
-
-    expect(validateApiVersion).toHaveBeenCalledWith(mockAdminSession, version)
-    expect(runBulkOperationQuery).toHaveBeenCalledWith({
-      adminSession: mockAdminSession,
-      query,
-      version,
-    })
-  })
-
-  test('does not validate version when not provided', async () => {
-    const query = '{ products { edges { node { id } } } }'
-    const mockResponse: BulkOperationRunQueryMutation['bulkOperationRunQuery'] = {
-      bulkOperation: createdBulkOperation,
-      userErrors: [],
-    }
-    vi.mocked(runBulkOperationQuery).mockResolvedValue(mockResponse)
-    vi.mocked(validateApiVersion).mockClear()
-
-    await executeBulkOperation({
-      organization: mockOrganization,
-      remoteApp: mockRemoteApp,
-      storeFqdn,
-      query,
-    })
-
-    expect(validateApiVersion).not.toHaveBeenCalled()
-  })
-
   test('renders warning when completed operation results contain userErrors', async () => {
     const query = '{ products { edges { node { id } } } }'
     const resultsWithErrors = '{"data":{"productUpdate":{"userErrors":[{"message":"invalid input"}]}},"__lineNumber":0}'

packages/app/src/cli/services/bulk-operations/execute-bulk-operation.ts

@@ -4,11 +4,12 @@ import {watchBulkOperation, shortBulkOperationPoll, type BulkOperation} from './
 import {formatBulkOperationStatus} from './format-bulk-operation-status.js'
 import {downloadBulkOperationResults} from './download-bulk-operation-results.js'
 import {extractBulkOperationId} from './bulk-operation-status.js'
+import {BULK_OPERATIONS_MIN_API_VERSION} from './constants.js'
 import {
   createAdminSessionAsApp,
   validateSingleOperation,
-  validateApiVersion,
   formatOperationInfo,
+  resolveApiVersion,
 } from '../graphql/common.js'
 import {OrganizationApp, Organization} from '../../models/organization.js'
 import {renderSuccess, renderInfo, renderError, renderWarning, TokenItem} from '@shopify/cli-kit/node/ui'
@@ -48,11 +49,21 @@ async function parseVariablesToJsonl(variables?: string[], variableFile?: string
 }
 
 export async function executeBulkOperation(input: ExecuteBulkOperationInput): Promise<void> {
-  const {organization, remoteApp, storeFqdn, query, variables, variableFile, outputFile, watch = false, version} = input
+  const {
+    organization,
+    remoteApp,
+    storeFqdn,
+    query,
+    variables,
+    variableFile,
+    outputFile,
+    watch = false,
+    version: versionFlag,
+  } = input
 
   const adminSession = await createAdminSessionAsApp(remoteApp, storeFqdn)
 
-  if (version) await validateApiVersion(adminSession, version)
+  const version = await resolveApiVersion(adminSession, versionFlag, BULK_OPERATIONS_MIN_API_VERSION)
 
   const variablesJsonl = await parseVariablesToJsonl(variables, variableFile)
 

packages/app/src/cli/services/execute-operation.test.ts

@@ -1,5 +1,5 @@
 import {executeOperation} from './execute-operation.js'
-import {createAdminSessionAsApp, validateApiVersion} from './graphql/common.js'
+import {createAdminSessionAsApp, resolveApiVersion} from './graphql/common.js'
 import {OrganizationApp, OrganizationSource} from '../models/organization.js'
 import {renderSuccess, renderError, renderSingleTask} from '@shopify/cli-kit/node/ui'
 import {adminRequestDoc} from '@shopify/cli-kit/node/api/admin'
@@ -32,6 +32,7 @@ describe('executeOperation', () => {
 
   beforeEach(() => {
     vi.mocked(createAdminSessionAsApp).mockResolvedValue(mockAdminSession)
+    vi.mocked(resolveApiVersion).mockResolvedValue('2024-07')
     vi.mocked(renderSingleTask).mockImplementation(async ({task}) => {
       return task(() => {})
     })
@@ -54,12 +55,13 @@ describe('executeOperation', () => {
     })
 
     expect(createAdminSessionAsApp).toHaveBeenCalledWith(mockRemoteApp, storeFqdn)
+    expect(resolveApiVersion).toHaveBeenCalledWith(mockAdminSession, undefined)
     expect(adminRequestDoc).toHaveBeenCalledWith({
       // parsed GraphQL document
       query: expect.any(Object),
       session: mockAdminSession,
       variables: undefined,
-      version: undefined,
+      version: '2024-07',
       responseOptions: {handleErrors: false},
     })
   })
@@ -107,7 +109,7 @@ describe('executeOperation', () => {
     const version = '2024-01'
     const mockResult = {data: {shop: {name: 'Test Shop'}}}
     vi.mocked(adminRequestDoc).mockResolvedValue(mockResult)
-    vi.mocked(validateApiVersion).mockResolvedValue()
+    vi.mocked(resolveApiVersion).mockResolvedValue(version)
 
     await executeOperation({
       organization: mockOrganization,
@@ -117,30 +119,14 @@ describe('executeOperation', () => {
       version,
     })
 
-    expect(validateApiVersion).toHaveBeenCalledWith(mockAdminSession, version)
+    expect(resolveApiVersion).toHaveBeenCalledWith(mockAdminSession, version)
     expect(adminRequestDoc).toHaveBeenCalledWith(
       expect.objectContaining({
         version,
       }),
     )
   })
 
-  test('does not validate version when not provided', async () => {
-    const query = 'query { shop { name } }'
-    const mockResult = {data: {shop: {name: 'Test Shop'}}}
-    vi.mocked(adminRequestDoc).mockResolvedValue(mockResult)
-    vi.mocked(validateApiVersion).mockClear()
-
-    await executeOperation({
-      organization: mockOrganization,
-      remoteApp: mockRemoteApp,
-      storeFqdn,
-      query,
-    })
-
-    expect(validateApiVersion).not.toHaveBeenCalled()
-  })
-
   test('writes formatted JSON results to stdout by default', async () => {
     const query = 'query { shop { name } }'
     const mockResult = {data: {shop: {name: 'Test Shop'}}}

packages/app/src/cli/services/execute-operation.ts

@@ -1,7 +1,7 @@
 import {
   createAdminSessionAsApp,
   validateSingleOperation,
-  validateApiVersion,
+  resolveApiVersion,
   formatOperationInfo,
 } from './graphql/common.js'
 import {OrganizationApp, Organization} from '../models/organization.js'
@@ -38,7 +38,11 @@ async function parseVariables(variables?: string): Promise<{[key: string]: unkno
 }
 
 export async function executeOperation(input: ExecuteOperationInput): Promise<void> {
-  const {organization, remoteApp, storeFqdn, query, variables, version, outputFile} = input
+  const {organization, remoteApp, storeFqdn, query, variables, version: versionFlag, outputFile} = input
+
+  const adminSession = await createAdminSessionAsApp(remoteApp, storeFqdn)
+
+  const version = await resolveApiVersion(adminSession, versionFlag)
 
   renderInfo({
     headline: 'Executing GraphQL operation.',
@@ -51,10 +55,6 @@ export async function executeOperation(input: ExecuteOperationInput): Promise<vo
     ],
   })
 
-  const adminSession = await createAdminSessionAsApp(remoteApp, storeFqdn)
-
-  if (version) await validateApiVersion(adminSession, version)
-
   const parsedVariables = await parseVariables(variables)
 
   validateSingleOperation(query)