Add typed JSON output to store authentication

Author: gonzaloriestra

packages/cli/README.md

@@ -3764,6 +3764,81 @@ DESCRIPTION
 
   Re-run this command if the stored token is missing, expires, or no longer has the scopes you need.
 
+  Output from `--json` conforms to the `StoreAuthResult` schema.
+
+  Use `--json-schema` to print the result, error, and event schemas.
+
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "store": {
+        "type": "string"
+      },
+      "userId": {
+        "type": "string"
+      },
+      "scopes": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "acquiredAt": {
+        "type": "string"
+      },
+      "expiresAt": {
+        "type": "string"
+      },
+      "refreshTokenExpiresAt": {
+        "type": "string"
+      },
+      "hasRefreshToken": {
+        "type": "boolean"
+      },
+      "associatedUser": {
+        "$ref": "#/definitions/StoreAuthAssociatedUser"
+      }
+    },
+    "required": [
+      "store",
+      "userId",
+      "scopes",
+      "acquiredAt",
+      "hasRefreshToken"
+    ],
+    "additionalProperties": false,
+    "title": "StoreAuthResult",
+    "definitions": {
+      "StoreAuthAssociatedUser": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "number"
+          },
+          "email": {
+            "type": "string"
+          },
+          "firstName": {
+            "type": "string"
+          },
+          "lastName": {
+            "type": "string"
+          },
+          "accountOwner": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "$schema": "http://json-schema.org/draft-07/schema#"
+  }
+  ```
+
 EXAMPLES
   $ shopify store auth --store shop.myshopify.com --scopes read_products,write_products
 
@@ -3803,6 +3878,51 @@ DESCRIPTION
   Use this command to find stores that can be used with store-authenticated commands such as `shopify store execute`.
   To list stores in a Shopify organization, run `shopify store list`.
 
+  Output from `--json` conforms to the `StoreAuthListResult` schema.
+
+  Use `--json-schema` to print the result, error, and event schemas.
+
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "sessions": {
+        "type": "array",
+        "items": {
+          "$ref": "#/definitions/StoreAuthListSession"
+        }
+      },
+      "message": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "sessions"
+    ],
+    "additionalProperties": false,
+    "title": "StoreAuthListResult",
+    "definitions": {
+      "StoreAuthListSession": {
+        "type": "object",
+        "properties": {
+          "subdomain": {
+            "type": "string"
+          },
+          "connected": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "subdomain",
+          "connected"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "$schema": "http://json-schema.org/draft-07/schema#"
+  }
+  ```
+
 EXAMPLES
   $ shopify store auth list
 

packages/cli/oclif.manifest.json

@@ -7877,7 +7877,7 @@
       "args": {
       },
       "customPluginName": "@shopify/store",
-      "description": "Authenticates the app against the specified store for store commands and stores an online access token for later reuse.\n\nRe-run this command if the stored token is missing, expires, or no longer has the scopes you need.",
+      "description": "Authenticates the app against the specified store for store commands and stores an online access token for later reuse.\n\nRe-run this command if the stored token is missing, expires, or no longer has the scopes you need.\n\nOutput from `--json` conforms to the `StoreAuthResult` schema.\n\nUse `--json-schema` to print the result, error, and event schemas.\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"store\": {\n      \"type\": \"string\"\n    },\n    \"userId\": {\n      \"type\": \"string\"\n    },\n    \"scopes\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      }\n    },\n    \"acquiredAt\": {\n      \"type\": \"string\"\n    },\n    \"expiresAt\": {\n      \"type\": \"string\"\n    },\n    \"refreshTokenExpiresAt\": {\n      \"type\": \"string\"\n    },\n    \"hasRefreshToken\": {\n      \"type\": \"boolean\"\n    },\n    \"associatedUser\": {\n      \"$ref\": \"#/definitions/StoreAuthAssociatedUser\"\n    }\n  },\n  \"required\": [\n    \"store\",\n    \"userId\",\n    \"scopes\",\n    \"acquiredAt\",\n    \"hasRefreshToken\"\n  ],\n  \"additionalProperties\": false,\n  \"title\": \"StoreAuthResult\",\n  \"definitions\": {\n    \"StoreAuthAssociatedUser\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"id\": {\n          \"type\": \"number\"\n        },\n        \"email\": {\n          \"type\": \"string\"\n        },\n        \"firstName\": {\n          \"type\": \"string\"\n        },\n        \"lastName\": {\n          \"type\": \"string\"\n        },\n        \"accountOwner\": {\n          \"type\": \"boolean\"\n        }\n      },\n      \"required\": [\n        \"id\"\n      ],\n      \"additionalProperties\": false\n    }\n  },\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```",
       "descriptionWithMarkdown": "Authenticates the app against the specified store for store commands and stores an online access token for later reuse.\n\nRe-run this command if the stored token is missing, expires, or no longer has the scopes you need.",
       "examples": [
         "<%= config.bin %> <%= command.id %> --store shop.myshopify.com --scopes read_products,write_products",
@@ -7952,7 +7952,7 @@
       "args": {
       },
       "customPluginName": "@shopify/store",
-      "description": "Lists stores authenticated directly on this machine with `shopify store auth`.\n\nUse this command to find stores that can be used with store-authenticated commands such as `shopify store execute`.\nTo list stores in a Shopify organization, run `shopify store list`.",
+      "description": "Lists stores authenticated directly on this machine with `shopify store auth`.\n\nUse this command to find stores that can be used with store-authenticated commands such as `shopify store execute`.\nTo list stores in a Shopify organization, run `shopify store list`.\n\nOutput from `--json` conforms to the `StoreAuthListResult` schema.\n\nUse `--json-schema` to print the result, error, and event schemas.\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"sessions\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"$ref\": \"#/definitions/StoreAuthListSession\"\n      }\n    },\n    \"message\": {\n      \"type\": \"string\"\n    }\n  },\n  \"required\": [\n    \"sessions\"\n  ],\n  \"additionalProperties\": false,\n  \"title\": \"StoreAuthListResult\",\n  \"definitions\": {\n    \"StoreAuthListSession\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"subdomain\": {\n          \"type\": \"string\"\n        },\n        \"connected\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"subdomain\",\n        \"connected\"\n      ],\n      \"additionalProperties\": false\n    }\n  },\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```",
       "descriptionWithMarkdown": "Lists stores authenticated directly on this machine with `shopify store auth`.\n\nUse this command to find stores that can be used with store-authenticated commands such as `shopify store execute`.\nTo list stores in a Shopify organization, run `shopify store list`.",
       "enableJsonFlag": false,
       "examples": [

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

@@ -1,39 +1,38 @@
 import StoreAuth from './auth.js'
 import {authenticateStoreWithApp} from '../../services/store/auth/index.js'
-import {createStoreAuthPresenter} from '../../services/store/auth/result.js'
+import {presentStoreAuthResult} from '../../services/store/auth/result.js'
+import {storeAuthJsonOutputSchema} from '../../services/store/auth/types.js'
 import {describe, expect, test, vi} from 'vitest'
 
 vi.mock('../../services/store/auth/index.js')
 vi.mock('../../services/store/attribution.js')
-vi.mock('../../services/store/auth/result.js', () => ({
-  createStoreAuthPresenter: vi.fn((format: 'text' | 'json') => ({format})),
-}))
+vi.mock('../../services/store/auth/result.js')
+
+const authResult = {
+  store: 'shop.myshopify.com',
+  userId: '42',
+  scopes: ['read_products'],
+  acquiredAt: '2026-04-02T00:00:00.000Z',
+  hasRefreshToken: true,
+}
 
 describe('store auth command', () => {
   test('passes parsed flags through to the auth service', async () => {
+    vi.mocked(authenticateStoreWithApp).mockResolvedValue(authResult)
     await StoreAuth.run(['--store', 'shop.myshopify.com', '--scopes', 'read_products,write_products'])
 
-    expect(createStoreAuthPresenter).toHaveBeenCalledWith('text')
-    expect(authenticateStoreWithApp).toHaveBeenCalledWith(
-      {
-        store: 'shop.myshopify.com',
-        scopes: 'read_products,write_products',
-      },
-      {presenter: {format: 'text'}},
-    )
+    expect(authenticateStoreWithApp).toHaveBeenCalledWith({
+      store: 'shop.myshopify.com',
+      scopes: 'read_products,write_products',
+    })
+    expect(presentStoreAuthResult).toHaveBeenCalledWith(authResult, 'text')
   })
 
-  test('passes a json presenter when --json is provided', async () => {
+  test('presents JSON when --json is provided', async () => {
+    vi.mocked(authenticateStoreWithApp).mockResolvedValue(authResult)
     await StoreAuth.run(['--store', 'shop.myshopify.com', '--scopes', 'read_products', '--json'])
 
-    expect(createStoreAuthPresenter).toHaveBeenCalledWith('json')
-    expect(authenticateStoreWithApp).toHaveBeenCalledWith(
-      {
-        store: 'shop.myshopify.com',
-        scopes: 'read_products',
-      },
-      {presenter: {format: 'json'}},
-    )
+    expect(presentStoreAuthResult).toHaveBeenCalledWith(authResult, 'json')
   })
 
   test('defines the expected flags', () => {
@@ -44,4 +43,8 @@ describe('store auth command', () => {
     expect('port' in StoreAuth.flags).toBe(false)
     expect('client-secret-file' in StoreAuth.flags).toBe(false)
   })
+
+  test('exposes the JSON output schema', () => {
+    expect(StoreAuth.jsonOutputSchema).toBe(storeAuthJsonOutputSchema)
+  })
 })

packages/store/src/cli/commands/store/auth.ts

@@ -1,5 +1,6 @@
 import {authenticateStoreWithApp} from '../../services/store/auth/index.js'
-import {createStoreAuthPresenter} from '../../services/store/auth/result.js'
+import {presentStoreAuthResult} from '../../services/store/auth/result.js'
+import {storeAuthJsonOutputSchema} from '../../services/store/auth/types.js'
 import StoreCommand from '../../utilities/store-command.js'
 import {storeFlags} from '../../flags.js'
 import {globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
@@ -30,17 +31,17 @@ Re-run this command if the stored token is missing, expires, or no longer has th
     }),
   }
 
+  static get jsonOutputSchema() {
+    return storeAuthJsonOutputSchema
+  }
+
   public async run(): Promise<void> {
     const {flags} = await this.parse(StoreAuth)
 
-    await authenticateStoreWithApp(
-      {
-        store: flags.store,
-        scopes: flags.scopes,
-      },
-      {
-        presenter: createStoreAuthPresenter(flags.json ? 'json' : 'text'),
-      },
-    )
+    const result = await authenticateStoreWithApp({
+      store: flags.store,
+      scopes: flags.scopes,
+    })
+    presentStoreAuthResult(result, flags.json ? 'json' : 'text')
   }
 }

packages/store/src/cli/commands/store/auth/list.test.ts

@@ -1,32 +1,37 @@
 import StoreAuthList from './list.js'
 import {listStoreAuthSessions} from '../../../services/store/auth/list.js'
 import {writeStoreAuthListResult} from '../../../services/store/auth/list-result.js'
+import {storeAuthListJsonOutputSchema} from '../../../services/store/auth/list-types.js'
 import {describe, expect, test, vi} from 'vitest'
 
 vi.mock('../../../services/store/auth/list.js')
 vi.mock('../../../services/store/auth/list-result.js')
 
 describe('store auth list command', () => {
   test('lists direct store-auth sessions and writes text output by default', async () => {
-    vi.mocked(listStoreAuthSessions).mockReturnValue({sessions: []})
+    vi.mocked(listStoreAuthSessions).mockReturnValue({sessions: [], message: 'No stores.'})
 
     await StoreAuthList.run([])
 
     expect(listStoreAuthSessions).toHaveBeenCalledWith()
-    expect(writeStoreAuthListResult).toHaveBeenCalledWith({sessions: []}, 'text')
+    expect(writeStoreAuthListResult).toHaveBeenCalledWith({sessions: [], message: 'No stores.'}, 'text')
   })
 
   test('writes json output when requested', async () => {
-    vi.mocked(listStoreAuthSessions).mockReturnValue({sessions: []})
+    vi.mocked(listStoreAuthSessions).mockReturnValue({sessions: [], message: 'No stores.'})
 
     await StoreAuthList.run(['--json'])
 
-    expect(writeStoreAuthListResult).toHaveBeenCalledWith({sessions: []}, 'json')
+    expect(writeStoreAuthListResult).toHaveBeenCalledWith({sessions: [], message: 'No stores.'}, 'json')
   })
 
   test('does not expose organization or source-selection flags', () => {
     expect(StoreAuthList.flags.json).toBeDefined()
     expect(StoreAuthList.flags).not.toHaveProperty('organization-id')
     expect(StoreAuthList.flags).not.toHaveProperty('from')
   })
+
+  test('exposes the JSON output schema', () => {
+    expect(StoreAuthList.jsonOutputSchema).toBe(storeAuthListJsonOutputSchema)
+  })
 })

packages/store/src/cli/commands/store/auth/list.ts

@@ -1,5 +1,6 @@
 import {listStoreAuthSessions} from '../../../services/store/auth/list.js'
 import {writeStoreAuthListResult} from '../../../services/store/auth/list-result.js'
+import {storeAuthListJsonOutputSchema} from '../../../services/store/auth/list-types.js'
 import Command from '@shopify/cli-kit/node/base-command'
 import {globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
 
@@ -20,6 +21,10 @@ To list stores in a Shopify organization, run \`shopify store list\`.`
     ...jsonFlag,
   }
 
+  static get jsonOutputSchema() {
+    return storeAuthListJsonOutputSchema
+  }
+
   async run(): Promise<void> {
     const {flags} = await this.parse(StoreAuthList)
     const result = listStoreAuthSessions()

packages/store/src/cli/commands/store/stripe-auth.test.ts

@@ -1,17 +1,24 @@
 import StoreStripeAuth, {readSignupJwtFromStdin} from './stripe-auth.js'
 import {authenticateStoreWithApp} from '../../services/store/auth/index.js'
-import {createStoreAuthPresenter} from '../../services/store/auth/result.js'
+import {presentStoreAuthResult} from '../../services/store/auth/result.js'
 import {describe, expect, test, vi} from 'vitest'
 import {Readable} from 'stream'
 
 vi.mock('../../services/store/auth/index.js')
 vi.mock('../../services/store/attribution.js')
-vi.mock('../../services/store/auth/result.js', () => ({
-  createStoreAuthPresenter: vi.fn((format: 'text' | 'json') => ({format})),
-}))
+vi.mock('../../services/store/auth/result.js')
+
+const authResult = {
+  store: 'shop.myshopify.com',
+  userId: '42',
+  scopes: ['read_products'],
+  acquiredAt: '2026-04-02T00:00:00.000Z',
+  hasRefreshToken: true,
+}
 
 describe('store stripe-auth command', () => {
   test('passes signup JWT through to the auth service', async () => {
+    vi.mocked(authenticateStoreWithApp).mockResolvedValue(authResult)
     await StoreStripeAuth.run([
       '--store',
       'shop.myshopify.com',
@@ -21,18 +28,16 @@ describe('store stripe-auth command', () => {
       'signed.signup.jwt',
     ])
 
-    expect(createStoreAuthPresenter).toHaveBeenCalledWith('text')
-    expect(authenticateStoreWithApp).toHaveBeenCalledWith(
-      {
-        store: 'shop.myshopify.com',
-        scopes: 'read_products',
-        signup: 'signed.signup.jwt',
-      },
-      {presenter: {format: 'text'}},
-    )
+    expect(authenticateStoreWithApp).toHaveBeenCalledWith({
+      store: 'shop.myshopify.com',
+      scopes: 'read_products',
+      signup: 'signed.signup.jwt',
+    })
+    expect(presentStoreAuthResult).toHaveBeenCalledWith(authResult, 'text')
   })
 
-  test('passes a json presenter when --json is provided', async () => {
+  test('presents JSON when --json is provided', async () => {
+    vi.mocked(authenticateStoreWithApp).mockResolvedValue(authResult)
     await StoreStripeAuth.run([
       '--store',
       'shop.myshopify.com',
@@ -43,15 +48,7 @@ describe('store stripe-auth command', () => {
       '--json',
     ])
 
-    expect(createStoreAuthPresenter).toHaveBeenCalledWith('json')
-    expect(authenticateStoreWithApp).toHaveBeenCalledWith(
-      {
-        store: 'shop.myshopify.com',
-        scopes: 'read_products',
-        signup: 'signed.signup.jwt',
-      },
-      {presenter: {format: 'json'}},
-    )
+    expect(presentStoreAuthResult).toHaveBeenCalledWith(authResult, 'json')
   })
 
   test('defines the expected flags', () => {