Add support for Metafields to webhooks

Author: rsperko

packages/app/src/cli/models/app/app.test-data.ts

@@ -428,6 +428,7 @@ export async function testSingleWebhookSubscriptionExtension({
     topic,
     api_version: '2024-01',
     uri: 'https://my-app.com/webhooks',
+    metafields: [{namespace: 'custom', key: 'test'}],
   },
 }: {
   emptyConfig?: boolean

packages/app/src/cli/models/extensions/specifications/app_config_webhook.test.ts

@@ -61,4 +61,148 @@ describe('webhooks', () => {
       })
     })
   })
+
+  describe('validation', () => {
+    test('allows metafields when API version is 2025-04', () => {
+      // Given
+      const object = {
+        webhooks: {
+          api_version: '2025-04',
+          subscriptions: [
+            {
+              topics: ['orders/create'],
+              uri: 'https://example.com/webhooks',
+              metafields: [{namespace: 'custom', key: 'test'}],
+            },
+          ],
+        },
+      }
+
+      // When
+      const result = spec.schema.safeParse(object)
+
+      // Then
+      expect(result.success).toBe(true)
+    })
+
+    test('allows metafields when API version is unstable', () => {
+      // Given
+      const object = {
+        webhooks: {
+          api_version: 'unstable',
+          subscriptions: [
+            {
+              topics: ['orders/create'],
+              uri: 'https://example.com/webhooks',
+              metafields: [{namespace: 'custom', key: 'test'}],
+            },
+          ],
+        },
+      }
+
+      // When
+      const result = spec.schema.safeParse(object)
+
+      // Then
+      expect(result.success).toBe(true)
+    })
+
+    test('rejects metafields when API version is before 2025-04', () => {
+      // Given
+      const object = {
+        webhooks: {
+          api_version: '2024-01',
+          subscriptions: [
+            {
+              topics: ['orders/create'],
+              uri: 'https://example.com/webhooks',
+              metafields: [{namespace: 'custom', key: 'test'}],
+            },
+          ],
+        },
+      }
+
+      // When
+      const result = spec.schema.safeParse(object)
+
+      // Then
+      expect(result.success).toBe(false)
+      expect(result.error.issues[0].message).toBe(
+        'Webhook metafields are only supported in API version 2025-04 or later, or with version "unstable"',
+      )
+    })
+
+    test('allows configuration without metafields in older API versions', () => {
+      // Given
+      const object = {
+        webhooks: {
+          api_version: '2024-01',
+          subscriptions: [
+            {
+              topics: ['orders/create'],
+              uri: 'https://example.com/webhooks',
+            },
+          ],
+        },
+      }
+
+      // When
+      const result = spec.schema.safeParse(object)
+
+      // Then
+      expect(result.success).toBe(true)
+    })
+
+    test('allows empty metafields array in supported API versions', () => {
+      // Given
+      const object = {
+        webhooks: {
+          api_version: '2025-04',
+          subscriptions: [
+            {
+              topics: ['orders/create'],
+              uri: 'https://example.com/webhooks',
+              metafields: [],
+            },
+          ],
+        },
+      }
+
+      // When
+      const result = spec.schema.safeParse(object)
+
+      // Then
+      expect(result.success).toBe(true)
+    })
+
+    test('rejects malformed metafields', () => {
+      // Given
+      const object = {
+        webhooks: {
+          api_version: '2025-04',
+          subscriptions: [
+            {
+              topics: ['orders/create'],
+              uri: 'https://example.com/webhooks',
+              metafields: [
+                {
+                  // Missing required 'key' property
+                  namespace: 'custom',
+                  // Invalid additional property
+                  invalid_property: 'test',
+                },
+              ],
+            },
+          ],
+        },
+      }
+
+      // When
+      const result = spec.schema.safeParse(object)
+
+      // Then
+      expect(result.success).toBe(false)
+      expect(result.error.issues[0].message).toMatch(/Required/)
+    })
+  })
 })

packages/app/src/cli/models/extensions/specifications/app_config_webhook_schemas/webhook_subscription_schema.ts

@@ -18,6 +18,15 @@ export const WebhookSubscriptionSchema = zod.object({
   }),
   include_fields: zod.array(zod.string({invalid_type_error: 'Value must be a string'})).optional(),
   filter: zod.string({invalid_type_error: 'Value must be a string'}).optional(),
+  metafields: zod
+    .array(
+      zod.object({
+        namespace: zod.string({invalid_type_error: 'Metafield namespace must be a string'}),
+        key: zod.string({invalid_type_error: 'Metafield key must be a string'}),
+      }),
+      {invalid_type_error: 'Metafields must be an array of objects with namespace and key'},
+    )
+    .optional(),
   compliance_topics: zod
     .array(
       zod.enum([ComplianceTopic.CustomersRedact, ComplianceTopic.CustomersDataRequest, ComplianceTopic.ShopRedact]),

packages/app/src/cli/models/extensions/specifications/app_config_webhook_subscription.test.ts

@@ -53,4 +53,159 @@ describe('webhook_subscription', () => {
       })
     })
   })
+
+  describe('metafields validation', () => {
+    test('transforms metafields correctly in local to remote', () => {
+      // Given
+      const object = {
+        topics: ['products/create'],
+        uri: '/products',
+        metafields: [
+          {
+            namespace: 'custom',
+            key: 'test',
+          },
+        ],
+      }
+
+      const webhookSpec = spec
+
+      // When
+      const result = webhookSpec.transformLocalToRemote!(object, {
+        application_url: 'https://my-app-url.com/',
+      } as unknown as AppConfigurationWithoutPath)
+
+      // Then
+      expect(result).toEqual({
+        uri: 'https://my-app-url.com/products',
+        topics: ['products/create'],
+        metafields: [
+          {
+            namespace: 'custom',
+            key: 'test',
+          },
+        ],
+      })
+    })
+
+    test('preserves metafields in remote to local transform', () => {
+      // Given
+      const object = {
+        topic: 'products/create',
+        uri: 'https://my-app-url.com/products',
+        metafields: [
+          {
+            namespace: 'custom',
+            key: 'test',
+          },
+        ],
+      }
+
+      const webhookSpec = spec
+
+      // When
+      const result = webhookSpec.transformRemoteToLocal!(object)
+
+      // Then
+      expect(result).toMatchObject({
+        webhooks: {
+          subscriptions: [
+            {
+              topics: ['products/create'],
+              uri: 'https://my-app-url.com/products',
+              metafields: [
+                {
+                  namespace: 'custom',
+                  key: 'test',
+                },
+              ],
+            },
+          ],
+        },
+      })
+    })
+
+    test('rejects metafields with missing required properties', () => {
+      // Given
+      const object = {
+        topics: ['products/create'],
+        uri: '/products',
+        metafields: [
+          {
+            // Missing required 'key' property
+            namespace: 'custom',
+          },
+        ],
+      }
+
+      const webhookSpec = spec
+
+      // When
+      const result = webhookSpec.schema.safeParse({
+        webhooks: {
+          subscriptions: [object],
+        },
+      })
+
+      // Then
+      expect(result.success).toBe(false)
+      expect(result.error.issues[0].message).toMatch(/Required/)
+    })
+
+    test('rejects metafields with invalid property types', () => {
+      // Given
+      const object = {
+        topics: ['products/create'],
+        uri: '/products',
+        metafields: [
+          {
+            namespace: 123,
+            key: ['invalid'],
+          },
+        ],
+      }
+
+      const webhookSpec = spec
+
+      // When
+      const result = webhookSpec.schema.safeParse({
+        webhooks: {
+          subscriptions: [object],
+        },
+      })
+
+      // Then
+      expect(result.success).toBe(false)
+      expect(result.error.issues[0].message).toBe('Required')
+    })
+
+    test('rejects metafields with additional invalid properties', () => {
+      // Given
+      const object = {
+        topics: ['products/create'],
+        uri: '/products',
+        metafields: [
+          {
+            namespace: 'custom',
+            key: 'test',
+            // Additional invalid property
+            invalid_property: 'test',
+          },
+        ],
+      }
+
+      const webhookSpec = spec
+
+      // When
+      const result = webhookSpec.schema.safeParse({
+        webhooks: {
+          subscriptions: [object],
+        },
+      })
+
+      // Then
+      expect(result.success).toBe(false)
+      expect(result.error.issues[0].message).toBe('Required')
+    })
+  })
 })

packages/app/src/cli/models/extensions/specifications/app_config_webhook_subscription.ts

@@ -13,6 +13,10 @@ interface TransformedWebhookSubscription {
   compliance_topics?: string[]
   include_fields?: string[]
   filter?: string
+  metafields?: {
+    namespace: string
+    key: string
+  }[]
 }
 
 export const SingleWebhookSubscriptionSchema = zod.object({
@@ -23,6 +27,15 @@ export const SingleWebhookSubscriptionSchema = zod.object({
   }),
   include_fields: zod.array(zod.string({invalid_type_error: 'Value must be a string'})).optional(),
   filter: zod.string({invalid_type_error: 'Value must be a string'}).optional(),
+  metafields: zod
+    .array(
+      zod.object({
+        namespace: zod.string({invalid_type_error: 'Metafield namespace must be a string'}),
+        key: zod.string({invalid_type_error: 'Metafield key must be a string'}),
+      }),
+      {invalid_type_error: 'Metafields must be an array of objects with namespace and key'},
+    )
+    .optional(),
 })
 
 /* this transforms webhooks remotely to be accepted by the TOML

packages/app/src/cli/models/extensions/specifications/types/app_config_webhook.ts

@@ -4,6 +4,10 @@ export interface WebhookSubscription {
   compliance_topics?: string[]
   include_fields?: string[]
   filter?: string
+  metafields?: {
+    namespace: string
+    key: string
+  }[]
 }
 
 interface PrivacyComplianceConfig {