Generate types for ui-extension intents

Author: JoviDeCroock

packages/app/src/cli/models/extensions/specifications/type-generation.test.ts

@@ -1,7 +1,141 @@
-import {createToolsTypeDefinition} from './type-generation.js'
+import {createIntentsTypeDefinition, createToolsTypeDefinition} from './type-generation.js'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {describe, expect, test} from 'vitest'
 
+describe('createIntentsTypeDefinition', () => {
+  test('returns empty string when intents array is empty', async () => {
+    // When
+    const result = await createIntentsTypeDefinition([])
+
+    // Then
+    expect(result).toBe('')
+  })
+
+  test('generates request and response types for a single intent schema', async () => {
+    // Given
+    const intents = [
+      {
+        action: 'create',
+        type: 'application/email',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            recipient: {type: 'string'},
+          },
+          required: ['recipient'],
+        },
+        outputSchema: {
+          type: 'object',
+          properties: {
+            success: {type: 'boolean'},
+          },
+        },
+      },
+    ]
+
+    // When
+    const result = await createIntentsTypeDefinition(intents)
+
+    // Then
+    expect(result).toBe(`interface CreateApplicationEmailIntentInput {
+  recipient: string;
+  [k: string]: unknown;
+}
+
+type CreateApplicationEmailIntentValue = unknown
+interface CreateApplicationEmailIntentOutput {
+  success?: boolean;
+  [k: string]: unknown;
+}
+
+interface CreateApplicationEmailIntentRequest {
+  action: "create";
+  type: "application/email";
+  data: CreateApplicationEmailIntentInput;
+  value?: CreateApplicationEmailIntentValue;
+}
+
+type ShopifyGeneratedIntentResponse<Data = unknown> = {
+  ok(data?: Data): Promise<void>;
+}
+
+type ShopifyGeneratedIntentsApi =
+  | {
+      request: CreateApplicationEmailIntentRequest;
+      response?: ShopifyGeneratedIntentResponse<CreateApplicationEmailIntentOutput>;
+    }
+`)
+  })
+
+  test('supports multiple intents with value schemas', async () => {
+    // Given
+    const intents = [
+      {
+        action: 'create',
+        type: 'application/email',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            recipient: {type: 'string'},
+          },
+        },
+      },
+      {
+        action: 'edit',
+        type: 'shopify/Product',
+        valueSchema: {
+          type: 'string',
+        },
+        inputSchema: {
+          type: 'object',
+          properties: {
+            title: {type: 'string'},
+          },
+        },
+        outputSchema: {
+          type: 'object',
+          properties: {
+            id: {type: 'string'},
+          },
+        },
+      },
+    ]
+
+    // When
+    const result = await createIntentsTypeDefinition(intents)
+
+    // Then
+    expect(result).toContain('interface CreateApplicationEmailIntentRequest')
+    expect(result).toContain('type CreateApplicationEmailIntentOutput = unknown')
+    expect(result).toContain('interface EditShopifyProductIntentRequest')
+    expect(result).toContain('type EditShopifyProductIntentValue = string')
+    expect(result).toContain('response?: ShopifyGeneratedIntentResponse<EditShopifyProductIntentOutput>;')
+  })
+
+  test('throws AbortError when intent action/type pairs are duplicated', async () => {
+    // Given
+    const intents = [
+      {
+        action: 'create',
+        type: 'application/email',
+        inputSchema: {type: 'object'},
+      },
+      {
+        action: 'create',
+        type: 'application/email',
+        inputSchema: {type: 'object'},
+      },
+    ]
+
+    // When & Then
+    await expect(createIntentsTypeDefinition(intents)).rejects.toThrow(
+      new AbortError(
+        'Intent "create:application/email" is defined multiple times. Intents must be unique within a target.',
+      ),
+    )
+  })
+})
+
 describe('createToolsTypeDefinition', () => {
   test('returns empty string when tools array is empty', async () => {
     // When

packages/app/src/cli/models/extensions/specifications/type-generation.ts

@@ -163,34 +163,85 @@ interface CreateTypeDefinitionOptions {
   targets: string[]
   apiVersion: string
   toolsTypeDefinition?: string
+  intentsTypeDefinition?: string
 }
 
-/**
- * Builds the shopify API type based on targets and optional tools type.
- * Returns null if no targets are provided.
- */
-function buildShopifyType(targets: string[], toolsTypeDefinition?: string): string | null {
-  const toolsSuffix = toolsTypeDefinition ? ' & { tools: ShopifyTools }' : ''
+interface ShopifyTypeOptions {
+  includesTools: boolean
+  includesIntents: boolean
+}
 
+function buildBaseShopifyType(targets: string[]): string | null {
   if (targets.length === 1) {
     const target = targets[0] ?? ''
-    return `import('@shopify/ui-extensions/${target}').Api${toolsSuffix}`
+    return `import('@shopify/ui-extensions/${target}').Api`
   }
 
   if (targets.length > 1) {
     const unionType = targets.map((target) => `import('@shopify/ui-extensions/${target}').Api`).join(' | ')
-    return `(${unionType})${toolsSuffix}`
+    return `(${unionType})`
   }
 
   return null
 }
 
+/**
+ * Builds the shopify API type based on targets and optional generated tool / intent types.
+ * Returns null if no targets are provided.
+ */
+function buildShopifyType(targets: string[], {includesTools, includesIntents}: ShopifyTypeOptions): string | null {
+  const baseShopifyType = buildBaseShopifyType(targets)
+  if (!baseShopifyType) return null
+
+  if (!includesTools && !includesIntents) {
+    return baseShopifyType
+  }
+
+  const wrappers = [
+    ...(includesIntents ? ['WithGeneratedIntents'] : []),
+    ...(includesTools ? ['WithGeneratedTools'] : []),
+  ]
+
+  return wrappers.reduce((shopifyType, wrapper) => `${wrapper}<${shopifyType}>`, baseShopifyType)
+}
+
+function buildShopifyUtilityTypes({includesTools, includesIntents}: ShopifyTypeOptions): string {
+  const utilityTypes: string[] = []
+
+  if (includesTools) {
+    utilityTypes.push(`type WithGeneratedTools<T> = T extends {tools?: infer Tools}
+  ? Omit<T, 'tools'> & {tools: Omit<NonNullable<Tools>, 'register'> & ShopifyTools}
+  : T & {tools: ShopifyTools}`)
+  }
+
+  if (includesIntents) {
+    utilityTypes.push(`type MergeGeneratedIntentResponse<Intents> = ShopifyGeneratedIntentsApi extends infer Generated
+  ? Generated extends {response?: infer GeneratedResponse}
+    ? Omit<Generated, 'response'> & {
+        response?: Intents extends {response?: infer BaseResponse}
+          ? Omit<NonNullable<BaseResponse>, 'ok'> & NonNullable<GeneratedResponse>
+          : NonNullable<GeneratedResponse>
+      }
+    : Generated
+  : never`)
+
+    utilityTypes.push(`type WithGeneratedIntents<T> = T extends {intents?: infer Intents}
+  ? Omit<T, 'intents'> & {
+      intents: Omit<NonNullable<Intents>, 'request' | 'response'> & MergeGeneratedIntentResponse<NonNullable<Intents>>
+    }
+  : T & {intents: ShopifyGeneratedIntentsApi}`)
+  }
+
+  return utilityTypes.join('\n\n')
+}
+
 export function createTypeDefinition({
   fullPath,
   typeFilePath,
   targets,
   apiVersion,
   toolsTypeDefinition,
+  intentsTypeDefinition,
 }: CreateTypeDefinitionOptions): string | null {
   try {
     // Validate that all targets can be resolved
@@ -208,14 +259,20 @@ export function createTypeDefinition({
     }
 
     const relativePath = relativizePath(fullPath, dirname(typeFilePath))
+    const includesTools = Boolean(toolsTypeDefinition)
+    const includesIntents = Boolean(intentsTypeDefinition)
 
-    const shopifyType = buildShopifyType(targets, toolsTypeDefinition)
+    const shopifyType = buildShopifyType(targets, {includesTools, includesIntents})
     if (!shopifyType) return null
 
+    const shopifyUtilityTypes = buildShopifyUtilityTypes({includesTools, includesIntents})
+
     const lines = [
       '//@ts-ignore',
       `declare module './${relativePath}' {`,
-      ...(toolsTypeDefinition ? [`  ${toolsTypeDefinition}`] : []),
+      ...(toolsTypeDefinition ? [toolsTypeDefinition] : []),
+      ...(intentsTypeDefinition ? [intentsTypeDefinition] : []),
+      ...(shopifyUtilityTypes ? [shopifyUtilityTypes] : []),
       `  const shopify: ${shopifyType};`,
       '  const globalThis: { shopify: typeof shopify };',
       '}',
@@ -269,6 +326,92 @@ const ToolDefinitionSchema: zod.ZodType<ToolDefinition> = zod.object({
 
 export const ToolsFileSchema = zod.array(ToolDefinitionSchema)
 
+interface IntentTypeDefinition {
+  action: string
+  type: string
+  inputSchema: object
+  valueSchema?: object
+  outputSchema?: object
+}
+
+interface IntentSchemaFile {
+  value?: object
+  inputSchema: object
+  outputSchema?: object
+}
+
+export const IntentSchemaFileSchema: zod.ZodType<IntentSchemaFile> = zod.object({
+  value: zod.object({}).passthrough().optional(),
+  inputSchema: zod.object({}).passthrough(),
+  outputSchema: zod.object({}).passthrough().optional(),
+})
+
+function intentTypeBaseName(intent: Pick<IntentTypeDefinition, 'action' | 'type'>): string {
+  return pascalize(`${intent.action} ${intent.type}`.replace(/[^a-zA-Z0-9]+/g, ' '))
+}
+
+/**
+ * Generates TypeScript types for shopify.intents.request and shopify.intents.response.ok
+ * based on intent schema definitions.
+ */
+export async function createIntentsTypeDefinition(intents: IntentTypeDefinition[]): Promise<string> {
+  if (intents.length === 0) return ''
+
+  const intentKeys = new Set<string>()
+  const typePromises = intents.map(async (intent) => {
+    const intentKey = `${intent.action}:${intent.type}`
+    if (intentKeys.has(intentKey)) {
+      throw new AbortError(`Intent "${intentKey}" is defined multiple times. Intents must be unique within a target.`)
+    }
+    intentKeys.add(intentKey)
+
+    const typeBaseName = intentTypeBaseName(intent)
+    const inputTypeName = `${typeBaseName}IntentInput`
+    const valueTypeName = `${typeBaseName}IntentValue`
+    const outputTypeName = `${typeBaseName}IntentOutput`
+    const requestTypeName = `${typeBaseName}IntentRequest`
+
+    const inputType = await formatJsonSchemaType(inputTypeName, intent.inputSchema)
+    const valueType = await formatJsonSchemaType(valueTypeName, intent.valueSchema)
+    const outputType = await formatJsonSchemaType(outputTypeName, intent.outputSchema)
+
+    const requestType = `interface ${requestTypeName} {
+  action: ${JSON.stringify(intent.action)};
+  type: ${JSON.stringify(intent.type)};
+  data: ${inputTypeName};
+  value?: ${valueTypeName};
+}`
+
+    return {
+      inputType,
+      valueType,
+      outputType,
+      requestType,
+      requestTypeName,
+      outputTypeName,
+    }
+  })
+
+  const types = await Promise.all(typePromises)
+
+  const generatedIntents = types
+    .map(({requestTypeName, outputTypeName}) => {
+      return `  | {
+      request: ${requestTypeName};
+      response?: ShopifyGeneratedIntentResponse<${outputTypeName}>;
+    }`
+    })
+    .join('\n')
+
+  return `${types
+    .map(
+      ({inputType, valueType, outputType, requestType}) => `${inputType}\n${valueType}\n${outputType}\n${requestType}`,
+    )
+    .join('\n\n')}\n\ntype ShopifyGeneratedIntentResponse<Data = unknown> = {
+  ok(data?: Data): Promise<void>;
+}\n\ntype ShopifyGeneratedIntentsApi =\n${generatedIntents}\n`
+}
+
 /**
  * Generates TypeScript types for shopify.tools.register based on tool definitions
  * @param tools - Array of tool definitions from tools.json
@@ -323,8 +466,15 @@ export async function createToolsTypeDefinition(tools: ToolDefinition[]): Promis
     .join('\n')}\ninterface ShopifyTools {\n${toolRegistrations}\n}\n`
 }
 
+function renameGeneratedType(typeDefinition: string, name: string): string {
+  return typeDefinition.replace(/^(interface|type|enum)\s+[A-Za-z0-9_]+/, `$1 ${name}`)
+}
+
 async function formatJsonSchemaType(name: string, schema?: object): Promise<string> {
-  const outputType = schema ? await compile(schema, name, {bannerComment: ''}) : `type ${name} = unknown`
-  // The json-schema-to-typescript library adds an export keyword to the type definition, we need to remove it
-  return outputType.startsWith('export ') ? outputType.slice(7) : outputType
+  if (!schema) return `type ${name} = unknown`
+
+  const outputType = await compile(schema, name, {bannerComment: ''})
+  const normalizedOutputType = outputType.startsWith('export ') ? outputType.slice(7) : outputType
+
+  return renameGeneratedType(normalizedOutputType, name)
 }