Add shopify store create trial command

Adds a programmatic way to create a Shopify trial store from the CLI,
backed by the Signups API's StoreCreate mutation.

- Registers `store:create:trial` in @shopify/store with flags for
  --name, --subdomain, --country (default US), and --json.
- Adds cli-kit Signups foundation: `shop-create` OAuth scope,
  `signupsApi` application + `ensureAuthenticatedSignups`,
  `signupsFqdn()`, and `signupsRequest` API helper.
- Regenerates oclif manifest, README, dev docs, and e2e snapshot.

Supersedes #7218.

Author: tizmagik

docs-shopify.dev/commands/examples/store-create-trial.example.sh

@@ -0,0 +1 @@
+shopify store create trial [flags]

docs-shopify.dev/commands/interfaces/store-create-trial.interface.ts

@@ -0,0 +1,42 @@
+// This is an autogenerated file. Don't edit this file manually.
+/**
+ * The following flags are available for the `store create trial` command:
+ * @publicDocs
+ */
+export interface storecreatetrial {
+  /**
+   * The country code for the store (e.g., US, CA, GB).
+   * @environment SHOPIFY_FLAG_STORE_COUNTRY
+   */
+  '-c, --country <value>'?: string
+
+  /**
+   * Output the result as JSON. Automatically disables color output.
+   * @environment SHOPIFY_FLAG_JSON
+   */
+  '-j, --json'?: ''
+
+  /**
+   * The name of the store.
+   * @environment SHOPIFY_FLAG_STORE_NAME
+   */
+  '-n, --name <value>'?: string
+
+  /**
+   * Disable color output.
+   * @environment SHOPIFY_FLAG_NO_COLOR
+   */
+  '--no-color'?: ''
+
+  /**
+   * The custom myshopify.com subdomain for the store.
+   * @environment SHOPIFY_FLAG_STORE_SUBDOMAIN
+   */
+  '--subdomain <value>'?: string
+
+  /**
+   * Increase the verbosity of the output.
+   * @environment SHOPIFY_FLAG_VERBOSE
+   */
+  '--verbose'?: ''
+}

docs-shopify.dev/commands/store-create-trial.doc.ts

@@ -0,0 +1,34 @@
+// This is an autogenerated file. Don't edit this file manually.
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'store create trial',
+  description: `Creates a new Shopify trial store associated with your account.`,
+  overviewPreviewDescription: `Create a new Shopify trial store.`,
+  type: 'command',
+  isVisualComponent: false,
+  defaultExample: {
+    codeblock: {
+      tabs: [
+        {
+          title: 'store create trial',
+          code: './examples/store-create-trial.example.sh',
+          language: 'bash',
+        },
+      ],
+      title: 'store create trial',
+    },
+  },
+  definitions: [
+  {
+    title: 'Flags',
+    description: 'The following flags are available for the `store create trial` command:',
+    type: 'storecreatetrial',
+  },
+  ],
+  category: 'store',
+  related: [
+  ],
+}
+
+export default data

packages/cli-kit/src/private/node/session.ts

@@ -92,6 +92,16 @@ interface BusinessPlatformAPIOAuthOptions {
   scopes: BusinessPlatformScope[]
 }
 
+/**
+ * A scope supported by the Signups API.
+ * The Signups API uses the Identity bearer token directly (no application token exchange).
+ */
+export type SignupsScope = 'shop-create'
+interface SignupsAPIOAuthOptions {
+  /** List of scopes to request permissions for. */
+  scopes: SignupsScope[]
+}
+
 /**
  * It represents the authentication requirements and
  * is the input necessary to trigger the authentication
@@ -103,6 +113,7 @@ export interface OAuthApplications {
   partnersApi?: PartnersAPIOAuthOptions
   businessPlatformApi?: BusinessPlatformAPIOAuthOptions
   appManagementApi?: AppManagementAPIOauthOptions
+  signupsApi?: SignupsAPIOAuthOptions
 }
 
 export interface OAuthSession {
@@ -111,6 +122,7 @@ export interface OAuthSession {
   storefront?: string
   businessPlatform?: string
   appManagement?: string
+  identity?: string
   userId: string
 }
 
@@ -399,6 +411,10 @@ async function tokensFor(applications: OAuthApplications, session: Session): Pro
     tokens.appManagement = session.applications[appId]?.accessToken
   }
 
+  if (applications.signupsApi) {
+    tokens.identity = session.identity.accessToken
+  }
+
   return tokens
 }
 
@@ -415,7 +431,8 @@ function getFlattenScopes(apps: OAuthApplications): string[] {
   const storefront = apps.storefrontRendererApi?.scopes ?? []
   const businessPlatform = apps.businessPlatformApi?.scopes ?? []
   const appManagement = apps.appManagementApi?.scopes ?? []
-  const requestedScopes = [...admin, ...partner, ...storefront, ...businessPlatform, ...appManagement]
+  const signups = apps.signupsApi?.scopes ?? []
+  const requestedScopes = [...admin, ...partner, ...storefront, ...businessPlatform, ...appManagement, ...signups]
   return allDefaultScopes(requestedScopes)
 }
 
@@ -426,6 +443,9 @@ function getFlattenScopes(apps: OAuthApplications): string[] {
  * @returns An object containing the scopes for each application.
  */
 function getExchangeScopes(apps: OAuthApplications): ExchangeScopes {
+  // Note: signupsApi is intentionally excluded here. The Signups API uses the Identity bearer
+  // token directly rather than an exchanged application token. Its scopes are included in
+  // getFlattenScopes so they appear on the Identity token, but no exchange is needed.
   const adminScope = apps.adminApi?.scopes ?? []
   const partnerScope = apps.partnersApi?.scopes ?? []
   const storefrontScopes = apps.storefrontRendererApi?.scopes ?? []

packages/cli-kit/src/private/node/session/scopes.test.ts

@@ -26,6 +26,12 @@ describe('allDefaultScopes', () => {
     ])
   })
 
+  test('transforms shop-create scope to full URI', async () => {
+    const got = allDefaultScopes(['shop-create'])
+
+    expect(got).toContain('https://api.shopify.com/auth/shop.create')
+  })
+
   test('includes App Management and Store Management', async () => {
     // When
     const got = allDefaultScopes([])

packages/cli-kit/src/private/node/session/scopes.ts

@@ -81,6 +81,8 @@ function scopeTransform(scope: string): string {
       return 'https://api.shopify.com/auth/organization.on-demand-user-access'
     case 'app-management':
       return 'https://api.shopify.com/auth/organization.apps.manage'
+    case 'shop-create':
+      return 'https://api.shopify.com/auth/shop.create'
     default:
       return scope
   }

packages/cli-kit/src/public/node/api/signups.test.ts

@@ -0,0 +1,60 @@
+import {signupsRequest} from './signups.js'
+import {graphqlRequest} from './graphql.js'
+import {handleDeprecations} from './partners.js'
+import {signupsFqdn} from '../context/fqdn.js'
+import {beforeEach, describe, expect, test, vi} from 'vitest'
+
+vi.mock('./graphql.js')
+vi.mock('../context/fqdn.js')
+
+const signupsFqdnValue = 'shopify.com'
+const url = `https://${signupsFqdnValue}/services/signups/graphql`
+const mockedToken = 'identity-token'
+
+beforeEach(() => {
+  vi.mocked(signupsFqdn).mockResolvedValue(signupsFqdnValue)
+})
+
+describe('signupsRequest', () => {
+  test('calls graphqlRequest with correct parameters', async () => {
+    vi.mocked(graphqlRequest).mockResolvedValue({storeCreate: {shopPermanentDomain: 'test.myshopify.com'}})
+    const query = 'mutation StoreCreate($signup: ShopInput!) { storeCreate(signup: $signup) { shopPermanentDomain } }'
+    const variables = {signup: {country: 'US'}}
+
+    await signupsRequest(query, mockedToken, variables)
+
+    expect(graphqlRequest).toHaveBeenCalledWith({
+      query,
+      api: 'Signups',
+      url,
+      token: mockedToken,
+      variables,
+      responseOptions: {onResponse: handleDeprecations},
+    })
+  })
+
+  test('calls graphqlRequest without variables when not provided', async () => {
+    vi.mocked(graphqlRequest).mockResolvedValue({})
+    const query = 'query { __schema { types { name } } }'
+
+    await signupsRequest(query, mockedToken)
+
+    expect(graphqlRequest).toHaveBeenCalledWith({
+      query,
+      api: 'Signups',
+      url,
+      token: mockedToken,
+      variables: undefined,
+      responseOptions: {onResponse: handleDeprecations},
+    })
+  })
+
+  test('returns the response from graphqlRequest', async () => {
+    const expectedResponse = {storeCreate: {shopPermanentDomain: 'new-store.myshopify.com', polling: false}}
+    vi.mocked(graphqlRequest).mockResolvedValue(expectedResponse)
+
+    const result = await signupsRequest('query', mockedToken)
+
+    expect(result).toEqual(expectedResponse)
+  })
+})

packages/cli-kit/src/public/node/api/signups.ts

@@ -0,0 +1,32 @@
+import {GraphQLVariables, graphqlRequest} from './graphql.js'
+import {handleDeprecations} from './partners.js'
+import {signupsFqdn} from '../context/fqdn.js'
+
+async function setupRequest(token: string) {
+  const api = 'Signups'
+  const fqdn = await signupsFqdn()
+  const url = `https://${fqdn}/services/signups/graphql`
+  return {
+    token,
+    api,
+    url,
+    responseOptions: {onResponse: handleDeprecations},
+  }
+}
+
+/**
+ * Executes a GraphQL query against the Signups API.
+ * Uses the Identity bearer token directly (no application token exchange).
+ *
+ * @param query - GraphQL query to execute.
+ * @param token - Identity access token.
+ * @param variables - GraphQL variables to pass to the query.
+ * @returns The response of the query of generic type <T>.
+ */
+export async function signupsRequest<T>(query: string, token: string, variables?: GraphQLVariables): Promise<T> {
+  return graphqlRequest<T>({
+    ...(await setupRequest(token)),
+    query,
+    variables,
+  })
+}

packages/cli-kit/src/public/node/context/fqdn.ts

@@ -102,6 +102,22 @@ export async function businessPlatformFqdn(): Promise<string> {
   }
 }
 
+/**
+ * It returns the Signups API service we should interact with.
+ *
+ * @returns Fully-qualified domain of the Signups service we should interact with.
+ */
+export async function signupsFqdn(): Promise<string> {
+  const environment = serviceEnvironment()
+  const productionFqdn = 'shopify.com'
+  switch (environment) {
+    case 'local':
+      return new DevServerCore().host('shopify')
+    default:
+      return productionFqdn
+  }
+}
+
 /**
  * It returns the Identity service we should interact with.
  *

packages/cli-kit/src/public/node/session.ts

@@ -15,6 +15,7 @@ import {
   BusinessPlatformScope,
   EnsureAuthenticatedAdditionalOptions,
   PartnersAPIScope,
+  SignupsScope,
   StorefrontRendererScope,
   ensureAuthenticated,
   setLastSeenAuthMethod,
@@ -274,6 +275,30 @@ ${outputToken.json(scopes)}
   return tokens.businessPlatform
 }
 
+/**
+ * Ensure that we have a valid session to access the Signups API.
+ * The Signups API uses the Identity bearer token directly (no application token exchange).
+ *
+ * @param scopes - Optional array of extra scopes to authenticate with.
+ * @param env - Optional environment variables to use.
+ * @param options - Optional extra options to use.
+ * @returns The Identity access token and user ID.
+ */
+export async function ensureAuthenticatedSignups(
+  scopes: SignupsScope[] = ['shop-create'],
+  env = process.env,
+  options: EnsureAuthenticatedAdditionalOptions = {},
+): Promise<{token: string; userId: string}> {
+  outputDebug(outputContent`Ensuring that the user is authenticated with the Signups API with the following scopes:
+${outputToken.json(scopes)}
+`)
+  const tokens = await ensureAuthenticated({signupsApi: {scopes}}, env, options)
+  if (!tokens.identity) {
+    throw new BugError('No identity token found after ensuring authenticated')
+  }
+  return {token: tokens.identity, userId: tokens.userId}
+}
+
 /**
  * Logout from Shopify.
  *