tapimo 0.14.0 → 0.15.0

package/src/apps/data/routes/webhooks.test.ts

@@ -1,4 +1,4 @@
-import { type Db, Webhooks as Core } from 'tapimo'
+import { type Db, Webhooks as Core } from 'tapimo/server'
 
 import * as Cursor from '../../../internal/Cursor.js'
 import * as TestApp from '../../../../test/App.js'
@@ -6,6 +6,54 @@ import * as Mppx from '../../../../test/Mppx.js'
 import * as Tempo from '../../../../test/Tempo.js'
 import * as Webhooks from './webhooks.js'
 
+type JsonSchema = {
+  $ref?: string
+  anyOf?: readonly JsonSchema[]
+  description?: string
+  enum?: readonly string[]
+  examples?: readonly unknown[]
+  format?: string
+  oneOf?: readonly JsonSchema[]
+  properties?: Record<string, JsonSchema>
+  required?: readonly string[]
+  title?: string
+  type?: string
+}
+
+type OpenApiOperation = {
+  operationId?: string
+  requestBody?: { content?: { 'application/json'?: { schema?: JsonSchema } } }
+  responses?: Record<string, { content?: { 'application/json'?: { schema?: JsonSchema } } }>
+}
+
+type OpenApiDocument = {
+  components: { schemas: Record<string, JsonSchema> }
+  paths: Record<string, Record<string, OpenApiOperation>>
+  webhooks?: Record<string, Record<string, OpenApiOperation>>
+}
+
+/** Resolves one component reference from the generated OpenAPI document. */
+function resolveSchema(spec: OpenApiDocument, value: JsonSchema | undefined) {
+  if (!value?.$ref) return value
+  const name = value.$ref.split('/').at(-1)
+  if (!name) throw new Error(`Invalid OpenAPI component ref ${value.$ref}`)
+  return spec.components.schemas[name]
+}
+
+/** Returns the generated JSON success schema for an operation. */
+function successSchema(operation: OpenApiOperation) {
+  return operation.responses?.['200']?.content?.['application/json']?.schema
+}
+
+/** Returns the exact generated error-code enum for a status. */
+function errorCodes(spec: OpenApiDocument, operation: OpenApiOperation, status: number) {
+  const envelope = resolveSchema(
+    spec,
+    operation.responses?.[String(status)]?.content?.['application/json']?.schema,
+  )
+  return resolveSchema(spec, envelope?.properties?.['error'])?.properties?.['code']?.enum
+}
+
 /** API key with both webhook scopes, owned by `org_test`. */
 const writer = {
   id: 'key_writer',
@@ -110,7 +158,7 @@ describe('feature gate', () => {
     expect(body.error?.code).toMatchInlineSnapshot(`"webhooks_not_enabled"`)
   })
 
-  test('does not register funding events without a host producer', async () => {
+  test('does not register routes events without a host producer', async () => {
     const app = TestApp.client({
       auth: { keys: [writer] },
       webhook: { supportedChainIds: [4217, 42431] },
@@ -120,18 +168,18 @@ describe('feature gate', () => {
     const created = await app.v1.webhooks.$post(
       {
         json: {
-          destination: { type: 'url', url: 'https://example.com/funding' },
-          eventType: 'funding:deposit.updated',
+          destination: { type: 'url', url: 'https://example.com/routes' },
+          eventType: 'routes:deposit.updated',
         },
       },
       as(writer),
     )
 
     expect(catalogBody.data.map((eventType) => eventType.type)).not.toContain(
-      'funding:deposit.updated',
+      'routes:deposit.updated',
     )
     expect(catalogBody.data.map((eventType) => eventType.type)).not.toContain(
-      'funding:transfer.updated',
+      'routes:transfer.updated',
     )
     expect(created.status).toBe(400)
   })
@@ -211,8 +259,8 @@ describe('access matrix', () => {
     expect(body.data.map((entry) => entry.type)).toMatchInlineSnapshot(`
       [
         "block:created",
-        "funding:deposit.updated",
-        "funding:transfer.updated",
+        "routes:deposit.updated",
+        "routes:transfer.updated",
         "log:emitted",
         "token:transfer",
         "transaction:included",
@@ -242,19 +290,19 @@ describe('access matrix', () => {
 })
 
 describe('CRUD lifecycle', () => {
-  test('requires funding read access to create a funding deposit subscription', async () => {
+  test('requires routes read access to create a route deposit subscription', async () => {
     const webhookWriter = {
-      id: 'key_funding_webhook_only',
-      orgId: 'org_funding_webhook_only',
+      id: 'key_routes_webhook_only',
+      orgId: 'org_routes_webhook_only',
       scopes: ['webhooks:write'],
-      token: 'secret_funding_webhook_only',
+      token: 'secret_routes_webhook_only',
     } satisfies TestApp.kvStore.Key
     const app = TestApp.client({ auth: { keys: [webhookWriter] } })
     const response = await app.v1.webhooks.$post(
       {
         json: {
-          destination: { type: 'url', url: 'https://example.com/funding' },
-          eventType: 'funding:deposit.updated',
+          destination: { type: 'url', url: 'https://example.com/routes' },
+          eventType: 'routes:deposit.updated',
         },
       },
       as(webhookWriter),
@@ -265,21 +313,21 @@ describe('CRUD lifecycle', () => {
     expect(body.error?.code).toBe('api_key_forbidden')
   })
 
-  test('captures funding transfer ownership scope without reading the RPC head', async () => {
+  test('captures route transfer ownership scope without reading the RPC head', async () => {
     const db = TestApp.database()
     const projectWriter = {
-      id: 'key_funding_webhook_project',
-      orgId: 'org_funding_webhook',
-      projectId: 'prj_funding_webhook',
-      scopes: ['funding:read', 'webhooks:write'],
-      token: 'secret_funding_webhook_project',
+      id: 'key_routes_webhook_project',
+      orgId: 'org_routes_webhook',
+      projectId: 'prj_routes_webhook',
+      scopes: ['routes:read', 'webhooks:write'],
+      token: 'secret_routes_webhook_project',
     } satisfies TestApp.kvStore.Key
     const app = TestApp.client({ auth: { keys: [projectWriter] }, db })
     const response = await app.v1.webhooks.$post(
       {
         json: {
-          destination: { type: 'url', url: 'https://example.com/funding' },
-          eventType: 'funding:transfer.updated',
+          destination: { type: 'url', url: 'https://example.com/routes' },
+          eventType: 'routes:transfer.updated',
           filters: { status: 'completed' },
         },
       },
@@ -300,40 +348,40 @@ describe('CRUD lifecycle', () => {
     expect(await Core.getCursor(db, body.id)).toBeNull()
   })
 
-  test('isolates funding subscriptions by API-key environment and project', async () => {
+  test('isolates routes subscriptions by API-key environment and project', async () => {
     const db = TestApp.database()
     const shared = {
-      orgId: 'org_funding_access',
-      scopes: ['funding:read', 'webhooks:read', 'webhooks:write'],
+      orgId: 'org_routes_access',
+      scopes: ['routes:read', 'webhooks:read', 'webhooks:write'],
     } as const
     const projectA = {
       ...shared,
-      id: 'key_funding_project_a',
-      projectId: 'prj_funding_a',
-      token: 'secret_funding_project_a',
+      id: 'key_routes_project_a',
+      projectId: 'prj_routes_a',
+      token: 'secret_routes_project_a',
     } satisfies TestApp.kvStore.Key
     const projectB = {
       ...shared,
-      id: 'key_funding_project_b',
-      projectId: 'prj_funding_b',
-      token: 'secret_funding_project_b',
+      id: 'key_routes_project_b',
+      projectId: 'prj_routes_b',
+      token: 'secret_routes_project_b',
     } satisfies TestApp.kvStore.Key
     const sandboxProjectB = {
       ...projectB,
       environment: 'sandbox',
-      id: 'key_funding_project_b_sandbox',
-      token: 'secret_funding_project_b_sandbox',
+      id: 'key_routes_project_b_sandbox',
+      token: 'secret_routes_project_b_sandbox',
     } satisfies TestApp.kvStore.Key
     const projectBWebhookReader = {
       ...projectB,
-      id: 'key_funding_project_b_webhook_reader',
+      id: 'key_routes_project_b_webhook_reader',
       scopes: ['webhooks:read'],
-      token: 'secret_funding_project_b_webhook_reader',
+      token: 'secret_routes_project_b_webhook_reader',
     } satisfies TestApp.kvStore.Key
     const organization = {
       ...shared,
-      id: 'key_funding_organization',
-      token: 'secret_funding_organization',
+      id: 'key_routes_organization',
+      token: 'secret_routes_organization',
     } satisfies TestApp.kvStore.Key
     const app = TestApp.client({
       auth: {
@@ -345,7 +393,7 @@ describe('CRUD lifecycle', () => {
       chainId: 4217,
       destination: { type: 'url', url: 'https://example.com/project-b' },
       environment: 'production',
-      eventType: 'funding:transfer.updated',
+      eventType: 'routes:transfer.updated',
       owner: { orgId: shared.orgId, type: 'api_key' },
       projectId: projectB.projectId,
     })
@@ -1282,6 +1330,534 @@ describe('OpenAPI visibility', () => {
     `)
   })
 
+  test('publishes generator-ready contracts and exact errors', async () => {
+    const app = TestApp.create({ auth: { keys: [writer] } })
+    const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+    const routes = [
+      ['get', '/v1/webhooks/event-types'],
+      ['post', '/v1/webhooks'],
+      ['get', '/v1/webhooks'],
+      ['get', '/v1/webhooks/{id}'],
+      ['get', '/v1/webhooks/{id}/deliveries'],
+      ['post', '/v1/webhooks/{id}/ping'],
+      ['post', '/v1/webhooks/{id}/deliveries/{deliveryId}/retry'],
+      ['patch', '/v1/webhooks/{id}'],
+      ['delete', '/v1/webhooks/{id}'],
+    ] as const
+
+    const operations = routes.map(([method, path]) => {
+      const operation = spec.paths[path]?.[method]
+      if (!operation) throw new Error(`Missing ${method.toUpperCase()} ${path}`)
+      return {
+        errors: Object.fromEntries(
+          [400, 401, 403, 404, 502]
+            .map((status) => [status, errorCodes(spec, operation, status)] as const)
+            .filter((entry) => entry[1] !== undefined),
+        ),
+        operationId: operation.operationId,
+        request: operation.requestBody?.content?.['application/json']?.schema?.$ref,
+        response: successSchema(operation)?.$ref,
+        route: `${method.toUpperCase()} ${path}`,
+      }
+    })
+
+    const componentNames = Object.keys(spec.components.schemas)
+      .filter(
+        (name) =>
+          name.startsWith('Webhook') ||
+          name.startsWith('CreateWebhook') ||
+          name === 'DeleteWebhookResponse' ||
+          name === 'PingWebhookResponse' ||
+          name === 'RetryWebhookDeliveryResponse' ||
+          name === 'UpdateWebhookRequest',
+      )
+      .sort()
+    const webhook = spec.components.schemas['Webhook']
+    const list = spec.components.schemas['WebhookList']
+    const delivery = spec.components.schemas['WebhookDelivery']
+    const deliveryList = spec.components.schemas['WebhookDeliveryList']
+    const eventTypes = spec.components.schemas['WebhookEventTypeList']
+    const envelope = spec.components.schemas['WebhookEventEnvelope']
+    const comparison = spec.components.schemas['WebhookLogFilters']?.properties?.[
+      'blockNumber'
+    ]?.anyOf?.find((branch) => branch.type === 'object')
+
+    expect(comparison?.examples).toStrictEqual([{ gte: '0x1' }])
+    expect(Webhooks.schema.compare.safeParse(comparison?.examples?.[0]).success).toBe(true)
+
+    expect({
+      components: componentNames,
+      examples: {
+        deliveries: deliveryList?.properties?.['data']?.examples,
+        eventTypes: eventTypes?.properties?.['data']?.examples,
+        logFilters: spec.components.schemas['WebhookLogFilters']?.examples,
+        logRequest: spec.components.schemas['CreateWebhookLogRequest']?.examples,
+        webhooks: list?.properties?.['data']?.examples,
+      },
+      formats: {
+        createdAt: webhook?.properties?.['createdAt']?.format,
+        requestUrl: delivery?.properties?.['requestUrl']?.format,
+        updatedAt: webhook?.properties?.['updatedAt']?.format,
+      },
+      operations,
+      outbound:
+        spec.webhooks?.['event']?.['post']?.requestBody?.content?.['application/json']?.schema
+          ?.$ref,
+      outboundChainIds: envelope?.oneOf?.map((variant) => variant.properties?.['chainId']),
+      variants: envelope?.oneOf?.map((variant) => ({
+        data:
+          variant.properties?.['data']?.$ref ??
+          (variant.properties?.['data'] ? 'inline' : undefined),
+        title: variant.title,
+      })),
+    }).toMatchInlineSnapshot(`
+      {
+        "components": [
+          "CreateWebhookBlockRequest",
+          "CreateWebhookLogRequest",
+          "CreateWebhookRequest",
+          "CreateWebhookResponse",
+          "CreateWebhookRoutesDepositRequest",
+          "CreateWebhookRoutesTransferRequest",
+          "CreateWebhookTransactionRequest",
+          "CreateWebhookTransferRequest",
+          "DeleteWebhookResponse",
+          "PingWebhookResponse",
+          "RetryWebhookDeliveryResponse",
+          "UpdateWebhookRequest",
+          "Webhook",
+          "WebhookBlockEvent",
+          "WebhookBlockFilters",
+          "WebhookContext",
+          "WebhookDelivery",
+          "WebhookDeliveryList",
+          "WebhookDestination",
+          "WebhookEventEnvelope",
+          "WebhookEventType",
+          "WebhookEventTypeList",
+          "WebhookList",
+          "WebhookLogEvent",
+          "WebhookLogFilters",
+          "WebhookNotFoundOrWebhooksNotEnabledError",
+          "WebhookPingEvent",
+          "WebhookPublicDestination",
+          "WebhookRoutesDepositFilters",
+          "WebhookRoutesTransferFilters",
+          "WebhookSubscriptionEventType",
+          "WebhookTransactionEvent",
+          "WebhookTransactionFilters",
+          "WebhookTransferEvent",
+          "WebhookTransferFilters",
+          "WebhooksNotEnabledError",
+        ],
+        "examples": {
+          "deliveries": [
+            [],
+          ],
+          "eventTypes": [
+            [
+              {
+                "description": "TIP-20 token transfer event.",
+                "type": "token:transfer",
+              },
+            ],
+          ],
+          "logFilters": [
+            {
+              "address": "0x20c0000000000000000000008f5425160ebe5525",
+            },
+          ],
+          "logRequest": [
+            {
+              "destination": {
+                "type": "url",
+                "url": "https://example.com/webhooks",
+              },
+              "eventType": "log:emitted",
+              "filters": {
+                "address": "0x20c0000000000000000000008f5425160ebe5525",
+              },
+            },
+          ],
+          "webhooks": [
+            [],
+          ],
+        },
+        "formats": {
+          "createdAt": "date-time",
+          "requestUrl": "uri",
+          "updatedAt": "date-time",
+        },
+        "operations": [
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "getWebhookEventTypes",
+            "request": undefined,
+            "response": "#/components/schemas/WebhookEventTypeList",
+            "route": "GET /v1/webhooks/event-types",
+          },
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "body_invalid",
+                "chain_id_unsupported",
+                "event_type_unsupported",
+                "filters_invalid",
+                "url_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+                "limit_exceeded",
+              ],
+              "404": [
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "createWebhook",
+            "request": "#/components/schemas/CreateWebhookRequest",
+            "response": "#/components/schemas/CreateWebhookResponse",
+            "route": "POST /v1/webhooks",
+          },
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "query_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "listWebhooks",
+            "request": undefined,
+            "response": "#/components/schemas/WebhookList",
+            "route": "GET /v1/webhooks",
+          },
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "param_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "webhook_not_found",
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "getWebhook",
+            "request": undefined,
+            "response": "#/components/schemas/Webhook",
+            "route": "GET /v1/webhooks/{id}",
+          },
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "param_invalid",
+                "query_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "webhook_not_found",
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "listWebhookDeliveries",
+            "request": undefined,
+            "response": "#/components/schemas/WebhookDeliveryList",
+            "route": "GET /v1/webhooks/{id}/deliveries",
+          },
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "param_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "webhook_not_found",
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "pingWebhook",
+            "request": undefined,
+            "response": "#/components/schemas/PingWebhookResponse",
+            "route": "POST /v1/webhooks/{id}/ping",
+          },
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "param_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "delivery_not_found",
+                "webhook_not_found",
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "retryWebhookDelivery",
+            "request": undefined,
+            "response": "#/components/schemas/RetryWebhookDeliveryResponse",
+            "route": "POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry",
+          },
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "body_invalid",
+                "destination_transition_invalid",
+                "filters_invalid",
+                "param_invalid",
+                "url_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "webhook_not_found",
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "updateWebhook",
+            "request": "#/components/schemas/UpdateWebhookRequest",
+            "response": "#/components/schemas/Webhook",
+            "route": "PATCH /v1/webhooks/{id}",
+          },
+          {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "param_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "webhook_not_found",
+                "webhooks_not_enabled",
+              ],
+              "502": [
+                "upstream_error",
+              ],
+            },
+            "operationId": "deleteWebhook",
+            "request": undefined,
+            "response": "#/components/schemas/DeleteWebhookResponse",
+            "route": "DELETE /v1/webhooks/{id}",
+          },
+        ],
+        "outbound": "#/components/schemas/WebhookEventEnvelope",
+        "outboundChainIds": [
+          {
+            "description": "Which Tempo network to query. Use the alias \`mainnet\` or \`testnet\`, or a numeric chain id (mainnet is \`4217\`).",
+            "examples": [
+              4217,
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer",
+          },
+          {
+            "description": "Which Tempo network to query. Use the alias \`mainnet\` or \`testnet\`, or a numeric chain id (mainnet is \`4217\`).",
+            "examples": [
+              4217,
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer",
+          },
+          {
+            "description": "Which Tempo network to query. Use the alias \`mainnet\` or \`testnet\`, or a numeric chain id (mainnet is \`4217\`).",
+            "examples": [
+              4217,
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer",
+          },
+          {
+            "description": "Which Tempo network to query. Use the alias \`mainnet\` or \`testnet\`, or a numeric chain id (mainnet is \`4217\`).",
+            "examples": [
+              4217,
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer",
+          },
+          {
+            "description": "Which Tempo network to query. Use the alias \`mainnet\` or \`testnet\`, or a numeric chain id (mainnet is \`4217\`).",
+            "examples": [
+              4217,
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer",
+          },
+          {
+            "description": "Which Tempo network to query. Use the alias \`mainnet\` or \`testnet\`, or a numeric chain id (mainnet is \`4217\`).",
+            "examples": [
+              4217,
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer",
+          },
+          {
+            "description": "Which Tempo network to query. Use the alias \`mainnet\` or \`testnet\`, or a numeric chain id (mainnet is \`4217\`).",
+            "examples": [
+              4217,
+            ],
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991,
+            "type": "integer",
+          },
+        ],
+        "variants": [
+          {
+            "data": "inline",
+            "title": "Transfer event",
+          },
+          {
+            "data": "inline",
+            "title": "Included transaction event",
+          },
+          {
+            "data": "inline",
+            "title": "Log event",
+          },
+          {
+            "data": "inline",
+            "title": "Block event",
+          },
+          {
+            "data": "inline",
+            "title": "Route deposit updated event",
+          },
+          {
+            "data": "inline",
+            "title": "Route transfer updated event",
+          },
+          {
+            "data": "inline",
+            "title": "Ping (test delivery)",
+          },
+        ],
+      }
+    `)
+  })
+
   test('omits the outbound `webhooks` section when the feature is disabled', async () => {
     const app = TestApp.create({ auth: { keys: [writer] }, webhook: false })
     const body = (await (await app.request('/openapi.json')).json()) as { webhooks?: object }
@@ -1293,20 +1869,14 @@ describe('OpenAPI visibility', () => {
     const app = TestApp.create({
       auth: { keys: [writer] },
     })
-    const body = (await (await app.request('/openapi.json')).json()) as {
-      webhooks?: {
-        event?: {
-          post?: {
-            parameters?: { name: string }[]
-            requestBody?: {
-              content?: { 'application/json'?: { schema?: { oneOf?: { title?: string }[] } } }
-            }
-          }
-        }
-      }
-    }
+    const body = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+    const operation = body.webhooks?.['event']?.['post']
 
-    expect(body.webhooks?.event?.post?.parameters?.map((p) => p.name)).toMatchInlineSnapshot(`
+    expect(
+      (operation as OpenApiOperation & { parameters?: { name: string }[] })?.parameters?.map(
+        (parameter) => parameter.name,
+      ),
+    ).toMatchInlineSnapshot(`
       [
         "tempo-signature",
         "tempo-event-id",
@@ -1315,16 +1885,19 @@ describe('OpenAPI visibility', () => {
     `)
     // Each envelope variant carries a `title` so Scalar renders a labelled
     // variant selector rather than collapsing the union to its first member.
-    const variants =
-      body.webhooks?.event?.post?.requestBody?.content?.['application/json']?.schema?.oneOf
+    const envelope = resolveSchema(
+      body,
+      operation?.requestBody?.content?.['application/json']?.schema,
+    )
+    const variants = envelope?.oneOf
     expect(variants?.map((v) => v.title)).toMatchInlineSnapshot(`
       [
         "Transfer event",
         "Included transaction event",
         "Log event",
         "Block event",
-        "Funding deposit updated event",
-        "Funding transfer updated event",
+        "Route deposit updated event",
+        "Route transfer updated event",
         "Ping (test delivery)",
       ]
     `)
@@ -1334,35 +1907,24 @@ describe('OpenAPI visibility', () => {
     const app = TestApp.create({
       auth: { keys: [writer] },
     })
-    const body = (await (await app.request('/openapi.json')).json()) as {
-      paths: {
-        '/v1/webhooks': {
-          post: {
-            requestBody: {
-              content: {
-                'application/json': {
-                  schema: {
-                    oneOf?: {
-                      title?: string
-                      properties?: { filters?: { properties?: Record<string, unknown> } }
-                    }[]
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-    const variants =
-      body.paths['/v1/webhooks'].post.requestBody.content['application/json'].schema.oneOf
+    const body = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+    const request = resolveSchema(
+      body,
+      body.paths['/v1/webhooks']?.['post']?.requestBody?.content?.['application/json']?.schema,
+    )
+    const variants = request?.oneOf
 
     // Each event type renders as a titled variant exposing only its own filters.
     expect(
-      variants?.map((v) => ({
-        filters: Object.keys(v.properties?.filters?.properties ?? {}),
-        title: v.title,
-      })),
+      variants?.map((variant) => {
+        const resolved = resolveSchema(body, variant)
+        return {
+          filters: Object.keys(
+            resolveSchema(body, resolved?.properties?.['filters'])?.properties ?? {},
+          ),
+          title: resolved?.title,
+        }
+      }),
     ).toMatchInlineSnapshot(`
       [
         {
@@ -1429,14 +1991,14 @@ describe('OpenAPI visibility', () => {
             "recipient",
             "status",
           ],
-          "title": "Funding deposit subscription",
+          "title": "Route deposit subscription",
         },
         {
           "filters": [
             "id",
             "status",
           ],
-          "title": "Funding transfer subscription",
+          "title": "Route transfer subscription",
         },
       ]
     `)