Route every store Organizations API request through one helper

Review follow-up.

The access guidance moves from tryMessage to nextSteps. `store create dev --json` and `store delete --json` only serialize message and nextSteps, so the guidance on which access to grant and where was lost from their JSON output. Command tests now cover both JSON paths.

withOrganizationStoreAccess, which each call site had to remember to wrap around its request, is replaced by organizationStoresRequestDoc in @Shopify/organizations. It sends a Business Platform Organizations API request for an organization and turns a refused one into OrganizationStoreAccessError. Every Organizations API request in the store and organizations packages now goes through it: store list, store create dev and its creation poll, store delete and its confirmation poll, and the shop lookup behind store info and store delete. A new request gets the same handling by using the helper.

Co-authored-by: Eddie Gao <eddie.gao@shopify.com>

Author: shopify-river

packages/organizations/src/cli/services/business-platform.test.ts

@@ -1,14 +1,16 @@
 import {
   isOrganizationAccessError,
   OrganizationStoreAccessError,
-  withOrganizationStoreAccess,
+  organizationStoresRequestDoc,
 } from './business-platform.js'
 import {describe, expect, test, vi, beforeEach} from 'vitest'
+import {businessPlatformOrganizationsRequestDoc} from '@shopify/cli-kit/node/api/business-platform'
 import {getAppAutomationToken} from '@shopify/cli-kit/node/environment'
 import {isServiceAccountTokenSet} from '@shopify/cli-kit/node/session'
 import {AbortError} from '@shopify/cli-kit/node/error'
 
 vi.mock('@shopify/cli-kit/node/environment')
+vi.mock('@shopify/cli-kit/node/api/business-platform')
 vi.mock('@shopify/cli-kit/node/session')
 
 const organization = {id: '299069', businessName: 'A Better Looking Shop'}
@@ -56,8 +58,12 @@ describe('OrganizationStoreAccessError', () => {
 
     expect(error).toBeInstanceOf(AbortError)
     expect(error.message).toBe("This service account can't manage dev stores in A Better Looking Shop.")
-    expect(JSON.stringify(error.tryMessage)).toContain('Dev store management')
-    expect(JSON.stringify(error.tryMessage)).toContain('Settings > Users > Security')
+    // The guidance lives in nextSteps, the field the store commands' --json output carries.
+    expect(error.tryMessage).toBeNull()
+    expect(error.nextSteps).toEqual([
+      'Give the service account Dev store management access in the Shopify admin under Settings > Users > Security.',
+      'Or use a token from a service account that has that access.',
+    ])
   })
 
   test('points a legacy automation token at service accounts', () => {
@@ -66,38 +72,54 @@ describe('OrganizationStoreAccessError', () => {
     const error = new OrganizationStoreAccessError(organization)
 
     expect(error.message).toBe("This automation token can't manage dev stores in A Better Looking Shop.")
-    expect(JSON.stringify(error.tryMessage)).toContain('SHOPIFY_SERVICE_ACCOUNT_TOKEN')
+    expect(error.nextSteps?.join(' ')).toContain('SHOPIFY_SERVICE_ACCOUNT_TOKEN')
   })
 
   test('talks about permission for a logged-in user', () => {
     const error = new OrganizationStoreAccessError(organization)
 
     expect(error.message).toBe("You don't have permission to manage dev stores in A Better Looking Shop.")
+    expect(error.nextSteps).toEqual([
+      "Check that you're logged in to the right account.",
+      'Or ask an organization admin for access.',
+    ])
+  })
+
+  test('falls back to the organization ID when the name is unknown', () => {
+    const error = new OrganizationStoreAccessError({id: '299069'})
+
+    expect(error.message).toBe("You don't have permission to manage dev stores in organization 299069.")
   })
 })
 
-describe('withOrganizationStoreAccess', () => {
-  test('returns the request result', async () => {
-    await expect(withOrganizationStoreAccess(organization, async () => 'ok')).resolves.toBe('ok')
+describe('organizationStoresRequestDoc', () => {
+  const request = {
+    query: {} as never,
+    token: 'token',
+    variables: {first: 1},
+    unauthorizedHandler: {type: 'token_refresh' as const, handler: async () => ({token: 'refreshed'})},
+  }
+
+  test("sends the request to the organization's Organizations API and returns the result", async () => {
+    vi.mocked(businessPlatformOrganizationsRequestDoc).mockResolvedValue({ok: true})
+
+    await expect(organizationStoresRequestDoc(organization, request)).resolves.toEqual({ok: true})
+    expect(businessPlatformOrganizationsRequestDoc).toHaveBeenCalledWith({...request, organizationId: '299069'})
   })
 
   test('replaces a refused request with the access error', async () => {
     vi.mocked(isServiceAccountTokenSet).mockReturnValue(true)
+    vi.mocked(businessPlatformOrganizationsRequestDoc).mockRejectedValue(handledClientError(401))
 
-    const result = withOrganizationStoreAccess(organization, async () => {
-      throw handledClientError(401)
-    })
-
-    await expect(result).rejects.toThrow("This service account can't manage dev stores in A Better Looking Shop.")
+    await expect(organizationStoresRequestDoc(organization, request)).rejects.toThrow(
+      "This service account can't manage dev stores in A Better Looking Shop.",
+    )
   })
 
   test('rethrows every other error unchanged', async () => {
-    const boom = new Error('boom')
+    const notFound = handledClientError(404)
+    vi.mocked(businessPlatformOrganizationsRequestDoc).mockRejectedValue(notFound)
 
-    await expect(
-      withOrganizationStoreAccess(organization, async () => {
-        throw boom
-      }),
-    ).rejects.toBe(boom)
+    await expect(organizationStoresRequestDoc(organization, request)).rejects.toBe(notFound)
   })
 })

packages/organizations/src/cli/services/business-platform.ts

@@ -1,5 +1,8 @@
-import {type Organization} from '../models/organization.js'
-import {type UnauthorizedHandler} from '@shopify/cli-kit/node/api/graphql'
+import {
+  businessPlatformOrganizationsRequestDoc,
+  type BusinessPlatformOrganizationsRequestOptions,
+} from '@shopify/cli-kit/node/api/business-platform'
+import {type GraphQLVariables, type UnauthorizedHandler} from '@shopify/cli-kit/node/api/graphql'
 import {getAppAutomationToken} from '@shopify/cli-kit/node/environment'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {ensureAuthenticatedBusinessPlatform, isServiceAccountTokenSet} from '@shopify/cli-kit/node/session'
@@ -19,6 +22,14 @@ export function businessPlatformTokenRefreshHandler(
   }
 }
 
+/**
+ * The organization a request addresses. The name is optional because some callers only know the ID.
+ */
+export interface OrganizationReference {
+  id: string
+  businessName?: string
+}
+
 /**
  * Whether the Organizations API refused a request because the account can't act in the organization.
  *
@@ -40,54 +51,50 @@ export function isOrganizationAccessError(error: unknown): boolean {
 /**
  * The error to show when the Organizations API refused access to an organization's stores.
  *
- * Names the credential that was refused: the service account, a legacy automation token, or the logged-in user.
+ * Names the credential that was refused (the service account, a legacy automation token, or the logged-in user) and
+ * puts the way to fix it in `nextSteps`, which both the terminal banner and the store commands' `--json` output show.
  */
 export class OrganizationStoreAccessError extends AbortError {
-  constructor(organization: Organization) {
-    const where = ['in the Shopify admin under', {subdued: 'Settings > Users > Security'}]
+  constructor(organization: OrganizationReference) {
+    const name = organization.businessName ?? `organization ${organization.id}`
+    const where = 'in the Shopify admin under Settings > Users > Security'
 
     if (isServiceAccountTokenSet()) {
-      super(`This service account can't manage dev stores in ${organization.businessName}.`, [
-        'Give it',
-        {bold: 'Dev store management'},
-        'access',
-        ...where,
-        {char: ','},
-        'or use a token from a service account that has it.',
+      super(`This service account can't manage dev stores in ${name}.`, null, [
+        `Give the service account Dev store management access ${where}.`,
+        'Or use a token from a service account that has that access.',
       ])
     } else if (getAppAutomationToken()) {
-      super(`This automation token can't manage dev stores in ${organization.businessName}.`, [
-        'Store commands need a service account token with',
-        {bold: 'Dev store management'},
-        'access. Create one',
-        ...where,
-        'and set it in',
-        {command: 'SHOPIFY_SERVICE_ACCOUNT_TOKEN'},
-        {char: '.'},
+      super(`This automation token can't manage dev stores in ${name}.`, null, [
+        `Create a service account with Dev store management access ${where}.`,
+        'Set its token in the SHOPIFY_SERVICE_ACCOUNT_TOKEN environment variable.',
       ])
     } else {
-      super(
-        `You don't have permission to manage dev stores in ${organization.businessName}.`,
-        "Check that you're logged in to the right account, or ask an organization admin for access.",
-      )
+      super(`You don't have permission to manage dev stores in ${name}.`, null, [
+        "Check that you're logged in to the right account.",
+        'Or ask an organization admin for access.',
+      ])
     }
   }
 }
 
 /**
- * Runs an Organizations API request for the organization, turning a refused request into an
- * `OrganizationStoreAccessError` so the user learns which access is missing rather than seeing the HTTP status.
+ * Runs a Business Platform Organizations API request against an organization's stores.
+ *
+ * Every Organizations API request the store commands make goes through here, so a token that can't act in the
+ * organization gets the same `OrganizationStoreAccessError` from every command, instead of each call site having to
+ * remember to translate the HTTP status.
  *
  * @param organization - The organization the request addresses.
- * @param request - The request to run.
- * @returns The request's result.
+ * @param options - The request, without the organization ID, which comes from `organization`.
+ * @returns The response of the query.
  */
-export async function withOrganizationStoreAccess<T>(
-  organization: Organization,
-  request: () => Promise<T>,
-): Promise<T> {
+export async function organizationStoresRequestDoc<TResult, TVariables extends GraphQLVariables>(
+  organization: OrganizationReference,
+  options: Omit<BusinessPlatformOrganizationsRequestOptions<TResult, TVariables>, 'organizationId'>,
+): Promise<TResult> {
   try {
-    return await request()
+    return await businessPlatformOrganizationsRequestDoc({...options, organizationId: organization.id})
   } catch (error) {
     if (isOrganizationAccessError(error)) throw new OrganizationStoreAccessError(organization)
     throw error

packages/organizations/src/cli/services/dev/create-dev-store.ts

@@ -6,8 +6,7 @@ import {
   PollStoreCreationQuery,
 } from '../../api/graphql/business-platform-organizations/generated/poll_store_creation.js'
 import {Organization} from '../../models/organization.js'
-import {businessPlatformTokenRefreshHandler, withOrganizationStoreAccess} from '../business-platform.js'
-import {businessPlatformOrganizationsRequestDoc} from '@shopify/cli-kit/node/api/business-platform'
+import {businessPlatformTokenRefreshHandler, organizationStoresRequestDoc} from '../business-platform.js'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {outputContent, outputResult} from '@shopify/cli-kit/node/output'
 import {sleep} from '@shopify/cli-kit/node/system'
@@ -60,21 +59,18 @@ export async function createDevStore(options: CreateDevStoreOptions): Promise<st
   const token = await ensureAuthenticatedBusinessPlatform([], {allowAutomationToken: true})
   const unauthorizedHandler = businessPlatformTokenRefreshHandler()
 
-  const mutationResult = await withOrganizationStoreAccess(org, () =>
-    businessPlatformOrganizationsRequestDoc({
-      query: CreateAppDevelopmentStore,
-      token,
-      organizationId: org.id,
-      variables: {
-        shopName: name,
-        priceLookupKey: DEV_STORE_PLANS[plan],
-        prepopulateTestData: options.withDemoData ?? false,
-        developerPreviewHandle: options.featurePreview,
-        country: options.country,
-      },
-      unauthorizedHandler,
-    }),
-  )
+  const mutationResult = await organizationStoresRequestDoc(org, {
+    query: CreateAppDevelopmentStore,
+    token,
+    variables: {
+      shopName: name,
+      priceLookupKey: DEV_STORE_PLANS[plan],
+      prepopulateTestData: options.withDemoData ?? false,
+      developerPreviewHandle: options.featurePreview,
+      country: options.country,
+    },
+    unauthorizedHandler,
+  })
 
   const createAppDevelopmentStore = mutationResult.createAppDevelopmentStore
   if (!createAppDevelopmentStore) {
@@ -101,10 +97,9 @@ export async function createDevStore(options: CreateDevStoreOptions): Promise<st
         }
 
         // eslint-disable-next-line no-await-in-loop
-        const pollResult = await businessPlatformOrganizationsRequestDoc({
+        const pollResult = await organizationStoresRequestDoc(org, {
           query: PollStoreCreation,
           token,
-          organizationId: org.id,
           variables: {shopDomain},
           unauthorizedHandler,
         })

packages/organizations/src/index.ts

@@ -5,10 +5,10 @@ export type {Organization, OrganizationWithDetails, OrganizationStatus} from './
 export {organizationStatusValues} from './cli/models/organization.js'
 export {
   businessPlatformTokenRefreshHandler,
-  isOrganizationAccessError,
   OrganizationStoreAccessError,
-  withOrganizationStoreAccess,
+  organizationStoresRequestDoc,
 } from './cli/services/business-platform.js'
+export type {OrganizationReference} from './cli/services/business-platform.js'
 export {createDevStore, devStorePlanHandles} from './cli/services/dev/create-dev-store.js'
 export type {CreateDevStoreOptions, DevStorePlan} from './cli/services/dev/create-dev-store.js'
 export {devStoreNamePrompt, devStorePlanPrompt, devStoreDemoDataPrompt} from './cli/prompts/dev.js'

packages/store/src/cli/commands/store/create/dev.test.ts

@@ -1,7 +1,7 @@
 import StoreCreateDev from './dev.js'
 import {createDevStore, createDevStoreJsonOutputSchema} from '../../../services/store/create/dev.js'
 import {storeNamePrompt, storePlanPrompt, storeDemoDataPrompt} from '../../../prompts/store.js'
-import {selectOrg} from '@shopify/organizations'
+import {OrganizationStoreAccessError, selectOrg} from '@shopify/organizations'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {outputResult} from '@shopify/cli-kit/node/output'
 import {terminalSupportsPrompting} from '@shopify/cli-kit/node/system'
@@ -279,6 +279,32 @@ describe('store create dev command', () => {
     mockExit.mockRestore()
   })
 
+  test('includes how to grant a service account dev store access in the --json error', async () => {
+    vi.stubEnv('SHOPIFY_SERVICE_ACCOUNT_TOKEN', 'service-account-token')
+    vi.mocked(createDevStore).mockRejectedValueOnce(new OrganizationStoreAccessError(defaultOrg))
+    const mockExit = vi.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('process.exit')
+    }) as never)
+
+    await expect(
+      StoreCreateDev.run(['--name', 'my-test-store', '--plan', 'plus', '--organization-id', '12345', '--json']),
+    ).rejects.toThrow('process.exit')
+
+    const parsed = JSON.parse(vi.mocked(outputResult).mock.calls[0]![0] as string)
+    expect(parsed).toEqual({
+      error: true,
+      message: "This service account can't manage dev stores in Test Org.",
+      nextSteps: [
+        'Give the service account Dev store management access in the Shopify admin under Settings > Users > Security.',
+        'Or use a token from a service account that has that access.',
+      ],
+      exitCode: 1,
+    })
+
+    mockExit.mockRestore()
+    vi.unstubAllEnvs()
+  })
+
   test('outputs one standard bug error for unexpected failures when --json is active', async () => {
     vi.mocked(createDevStore).mockRejectedValueOnce(new Error('unexpected'))
 

packages/store/src/cli/commands/store/delete.test.ts

@@ -2,6 +2,7 @@ import StoreDelete from './delete.js'
 import {deleteDevStoreJsonOutputSchema} from '../../services/store/delete/types.js'
 import {deleteDevStore} from '../../services/store/delete/dev.js'
 import {resolveOrganizationForStore} from '../../utilities/store-lookup/organization.js'
+import {OrganizationStoreAccessError} from '@shopify/organizations'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {outputResult} from '@shopify/cli-kit/node/output'
 import {isTTY, renderDangerousConfirmationPrompt} from '@shopify/cli-kit/node/ui'
@@ -172,6 +173,33 @@ describe('store delete command', () => {
     mockExit.mockRestore()
   })
 
+  test('includes how to grant a service account dev store access in the --json error', async () => {
+    vi.stubEnv('SHOPIFY_SERVICE_ACCOUNT_TOKEN', 'service-account-token')
+    vi.mocked(deleteDevStore).mockRejectedValueOnce(new OrganizationStoreAccessError(defaultOrg))
+    const mockExit = vi.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('process.exit')
+    }) as never)
+
+    await expect(
+      StoreDelete.run(['--store', 'my-store.myshopify.com', '--organization-id', '12345', '--json', '--force']),
+    ).rejects.toThrow('process.exit')
+
+    const parsed = JSON.parse(vi.mocked(outputResult).mock.calls[0]![0] as string)
+    expect(deleteDevStoreJsonOutputSchema.validate(parsed)).toEqual(parsed)
+    expect(parsed).toEqual({
+      error: true,
+      message: "This service account can't manage dev stores in Test Org.",
+      nextSteps: [
+        'Give the service account Dev store management access in the Shopify admin under Settings > Users > Security.',
+        'Or use a token from a service account that has that access.',
+      ],
+      exitCode: 1,
+    })
+
+    mockExit.mockRestore()
+    vi.unstubAllEnvs()
+  })
+
   test('outputs structured JSON error when --json is active and organization resolution throws AbortError', async () => {
     vi.mocked(resolveOrganizationForStore).mockRejectedValueOnce(new AbortError('Could not resolve organization'))
     const mockExit = vi.spyOn(process, 'exit').mockImplementation((() => {

packages/store/src/cli/services/store/business-platform.ts

@@ -1 +1 @@
-export {businessPlatformTokenRefreshHandler, withOrganizationStoreAccess} from '@shopify/organizations'
+export {businessPlatformTokenRefreshHandler, organizationStoresRequestDoc} from '@shopify/organizations'