tapimo 0.14.0 → 0.15.1

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

@@ -1,7 +1,7 @@
 /** @module-tag localnet */
 
-import { Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
+import { Schema } from 'tapimo/server'
 import { Value as core_Value } from 'ox'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { Actions } from 'viem/tempo'
@@ -362,7 +362,7 @@ describe('GET /addresses/:address/balances', () => {
     expect(response.headers.get('server-timing')).toContain('token_logo;dur=')
     expect(response.headers.get('server-timing')).not.toContain('token_metadata;dur=')
     expect(pathUsd?.token.logoUri).toBe(
-      `http://localhost/assets/${runtime.chainId}/icons/${TestApp.tokenWithHolders}`,
+      `http://localhost/assets/${runtime.chainId}/icons/${TestApp.tokenWithHolders}?__response=svg-sandbox-v1`,
     )
   })
 

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

@@ -1,6 +1,6 @@
 /** @module-tag localnet */
 
-import { Schema } from 'tapimo'
+import { Schema } from 'tapimo/server'
 import { Hex } from 'ox'
 import { zeroHash } from 'viem'
 
@@ -80,6 +80,9 @@ describe('OpenAPI', () => {
         validBefore: spec.components.schemas.Transaction.properties.validBefore.anyOf[0].format,
       },
       hiddenCompatibilityRoute: spec.paths['/chains/{chainId}/blocks/by-timestamp'],
+      identifierParameter: operations.block.parameters.find(
+        (parameter: { name: string }) => parameter.name === 'block',
+      )?.schema,
       models: {
         blockList: spec.components.schemas.BlockList.properties.data.items,
         blockMeta: spec.components.schemas.Block.properties.meta,
@@ -147,6 +150,34 @@ describe('OpenAPI', () => {
           "validBefore": "date-time",
         },
         "hiddenCompatibilityRoute": undefined,
+        "identifierParameter": {
+          "anyOf": [
+            {
+              "enum": [
+                "latest",
+                "finalized",
+              ],
+              "examples": [
+                "latest",
+              ],
+              "type": "string",
+            },
+            {
+              "pattern": "^(0x[0-9a-fA-F]+|[0-9]+)$",
+              "type": "string",
+            },
+            {
+              "format": "date-time",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+              "type": "string",
+            },
+          ],
+          "examples": [
+            "1000000",
+            "latest",
+            "2023-11-14T22:13:20Z",
+          ],
+        },
         "models": {
           "blockList": {
             "$ref": "#/components/schemas/BlockSummary",
@@ -186,6 +217,14 @@ describe('OpenAPI', () => {
           },
           "rpcTransactionCalls": {
             "$ref": "#/components/schemas/RpcTransactionCall",
+            "examples": [
+              {
+                "data": "0xdeadbeef",
+                "input": "0xdeadbeef",
+                "to": null,
+                "value": "0x0",
+              },
+            ],
           },
           "rpcTransactionFeePayerSignature": {
             "$ref": "#/components/schemas/RpcTransactionSignatureEnvelope",
@@ -195,6 +234,12 @@ describe('OpenAPI', () => {
           },
           "transactionCalls": {
             "$ref": "#/components/schemas/TransactionCall",
+            "examples": [
+              {
+                "data": "0xdeadbeef",
+                "to": null,
+              },
+            ],
           },
           "transactionList": {
             "$ref": "#/components/schemas/Transaction",

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

@@ -1,10 +1,31 @@
 import { Address, Hash } from 'ox'
-import { Schema } from 'tapimo'
+import { Schema } from 'tapimo/server'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
 import * as Coingecko from './coingecko.js'
 
+type JsonSchema = {
+  $ref?: string
+  description?: string
+  enum?: readonly string[]
+  items?: JsonSchema
+  properties?: Record<string, JsonSchema>
+  required?: readonly string[]
+}
+type OpenApiResponse = {
+  $ref?: string
+  content?: Record<string, { schema?: JsonSchema }>
+}
+type OpenApiOperation = {
+  operationId?: string
+  responses?: Record<string, OpenApiResponse>
+}
+type OpenApiDocument = {
+  components: { schemas: Record<string, JsonSchema> }
+  paths: Record<string, { get?: OpenApiOperation }>
+}
+
 // The adapter addresses the chain positionally, mirroring the legacy `/gecko`
 // contract GeckoTerminal consumes.
 const chainId = String(Runtime.get().chainId)
@@ -12,6 +33,403 @@ const chainId = String(Runtime.get().chainId)
 /** pathUSD — known to exist and have supply on Moderato. */
 const pathUsd = '0x20c0000000000000000000000000000000000000'
 
+function component(spec: OpenApiDocument, name: string): JsonSchema {
+  const schema = spec.components.schemas[name]
+  if (!schema) throw new Error(`Missing OpenAPI component ${name}`)
+  return schema
+}
+
+function resolveSchema(spec: OpenApiDocument, schema: JsonSchema | undefined): JsonSchema {
+  if (!schema) throw new Error('Missing OpenAPI schema')
+  if (!schema.$ref) return schema
+  const name = schema.$ref.split('/').at(-1)
+  if (!name) throw new Error(`Invalid OpenAPI component ref ${schema.$ref}`)
+  return component(spec, name)
+}
+
+describe('OpenAPI', () => {
+  test('publishes generator-ready CoinGecko compatibility contracts', async () => {
+    const app = TestApp.create({ auth: false })
+    const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+    const operations = {
+      asset: spec.paths['/gecko/{chainId}/assets/{address}']?.get,
+      events: spec.paths['/gecko/{chainId}/events']?.get,
+      latestBlock: spec.paths['/gecko/{chainId}/latest-block']?.get,
+      pair: spec.paths['/gecko/{chainId}/pairs/{pairId}']?.get,
+      pairs: spec.paths['/gecko/{chainId}/pairs']?.get,
+    }
+    if (Object.values(operations).some((operation) => !operation))
+      throw new Error('Missing CoinGecko OpenAPI operation')
+
+    const summarizeError = (response: OpenApiResponse | undefined) => {
+      if (!response) return undefined
+      if (response.$ref) return { $ref: response.$ref }
+      const schema = response.content?.['application/json']?.schema
+      return resolveSchema(spec, schema).properties?.['error']?.properties?.['code']?.enum
+    }
+    const summarize = (operation: OpenApiOperation | undefined) => {
+      if (!operation) throw new Error('Missing CoinGecko OpenAPI operation')
+      return {
+        errors: Object.fromEntries(
+          [400, 401, 402, 403, 404, 429, 500, 502, 504]
+            .filter((status) => operation.responses?.[status])
+            .map((status) => [status, summarizeError(operation.responses?.[status])]),
+        ),
+        operationId: operation.operationId,
+        response: operation.responses?.['200']?.content?.['application/json']?.schema,
+      }
+    }
+    const components = {
+      asset: component(spec, 'CoinGeckoAsset'),
+      assetResponse: component(spec, 'CoinGeckoAssetResponse'),
+      block: component(spec, 'CoinGeckoBlock'),
+      eventsResponse: component(spec, 'CoinGeckoEventsResponse'),
+      latestBlockResponse: component(spec, 'CoinGeckoLatestBlockResponse'),
+      pair: component(spec, 'CoinGeckoPair'),
+      pairResponse: component(spec, 'CoinGeckoPairResponse'),
+      pairsResponse: component(spec, 'CoinGeckoPairsResponse'),
+      swapEvent: component(spec, 'CoinGeckoSwapEvent'),
+    }
+    const componentNames = Object.keys(spec.components.schemas)
+      .filter((name) => name.startsWith('CoinGecko'))
+      .sort()
+
+    expect({
+      components: componentNames,
+      models: {
+        asset: components.assetResponse.properties?.['asset'],
+        block: components.latestBlockResponse.properties?.['block'],
+        eventBlock: components.swapEvent.properties?.['block'],
+        events: components.eventsResponse.properties?.['events']?.items,
+        pair: components.pairResponse.properties?.['pair'],
+        pairs: components.pairsResponse.properties?.['pairs']?.items,
+      },
+      operations: Object.fromEntries(
+        Object.entries(operations).map(([name, operation]) => [name, summarize(operation)]),
+      ),
+      required: {
+        asset: components.asset.required,
+        block: components.block.required,
+        pair: components.pair.required,
+        swapEvent: components.swapEvent.required,
+      },
+      undescribedComponents: componentNames.filter((name) => !component(spec, name).description),
+    }).toMatchInlineSnapshot(`
+      {
+        "components": [
+          "CoinGeckoAddress",
+          "CoinGeckoAsset",
+          "CoinGeckoAssetResponse",
+          "CoinGeckoBlock",
+          "CoinGeckoEventsResponse",
+          "CoinGeckoLatestBlockResponse",
+          "CoinGeckoPair",
+          "CoinGeckoPairResponse",
+          "CoinGeckoPairToken",
+          "CoinGeckoPairsResponse",
+          "CoinGeckoSwapEvent",
+        ],
+        "models": {
+          "asset": {
+            "$ref": "#/components/schemas/CoinGeckoAsset",
+          },
+          "block": {
+            "$ref": "#/components/schemas/CoinGeckoBlock",
+          },
+          "eventBlock": {
+            "$ref": "#/components/schemas/CoinGeckoBlock",
+          },
+          "events": {
+            "$ref": "#/components/schemas/CoinGeckoSwapEvent",
+          },
+          "pair": {
+            "$ref": "#/components/schemas/CoinGeckoPair",
+          },
+          "pairs": {
+            "$ref": "#/components/schemas/CoinGeckoPair",
+          },
+        },
+        "operations": {
+          "asset": {
+            "errors": {
+              "400": [
+                "address_invalid",
+                "api_key_malformed",
+                "chain_id_invalid",
+                "chain_id_unsupported",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "402": {
+                "$ref": "#/components/responses/PaymentRequired",
+              },
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "not_found",
+              ],
+              "429": {
+                "$ref": "#/components/responses/RateLimited",
+              },
+              "500": {
+                "$ref": "#/components/responses/InternalError",
+              },
+              "502": [
+                "upstream_error",
+              ],
+              "504": {
+                "$ref": "#/components/responses/RequestTimeout",
+              },
+            },
+            "operationId": "coingeckoAsset",
+            "response": {
+              "$ref": "#/components/schemas/CoinGeckoAssetResponse",
+            },
+          },
+          "events": {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "chain_id_invalid",
+                "chain_id_unsupported",
+                "query_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "402": {
+                "$ref": "#/components/responses/PaymentRequired",
+              },
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "not_found",
+              ],
+              "429": {
+                "$ref": "#/components/responses/RateLimited",
+              },
+              "500": {
+                "$ref": "#/components/responses/InternalError",
+              },
+              "502": [
+                "upstream_error",
+              ],
+              "504": {
+                "$ref": "#/components/responses/RequestTimeout",
+              },
+            },
+            "operationId": "coingeckoEvents",
+            "response": {
+              "$ref": "#/components/schemas/CoinGeckoEventsResponse",
+            },
+          },
+          "latestBlock": {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "chain_id_invalid",
+                "chain_id_unsupported",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "402": {
+                "$ref": "#/components/responses/PaymentRequired",
+              },
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "not_found",
+              ],
+              "429": {
+                "$ref": "#/components/responses/RateLimited",
+              },
+              "500": {
+                "$ref": "#/components/responses/InternalError",
+              },
+              "502": [
+                "upstream_error",
+              ],
+              "504": {
+                "$ref": "#/components/responses/RequestTimeout",
+              },
+            },
+            "operationId": "coingeckoLatestBlock",
+            "response": {
+              "$ref": "#/components/schemas/CoinGeckoLatestBlockResponse",
+            },
+          },
+          "pair": {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "chain_id_invalid",
+                "chain_id_unsupported",
+                "pair_id_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "402": {
+                "$ref": "#/components/responses/PaymentRequired",
+              },
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "404": [
+                "not_found",
+              ],
+              "429": {
+                "$ref": "#/components/responses/RateLimited",
+              },
+              "500": {
+                "$ref": "#/components/responses/InternalError",
+              },
+              "502": [
+                "upstream_error",
+              ],
+              "504": {
+                "$ref": "#/components/responses/RequestTimeout",
+              },
+            },
+            "operationId": "coingeckoPair",
+            "response": {
+              "$ref": "#/components/schemas/CoinGeckoPairResponse",
+            },
+          },
+          "pairs": {
+            "errors": {
+              "400": [
+                "api_key_malformed",
+                "chain_id_invalid",
+                "chain_id_unsupported",
+                "query_invalid",
+              ],
+              "401": [
+                "api_key_invalid",
+                "api_key_missing",
+                "unauthorized",
+              ],
+              "402": {
+                "$ref": "#/components/responses/PaymentRequired",
+              },
+              "403": [
+                "api_key_forbidden",
+                "api_key_ip_forbidden",
+                "forbidden",
+              ],
+              "429": {
+                "$ref": "#/components/responses/RateLimited",
+              },
+              "500": {
+                "$ref": "#/components/responses/InternalError",
+              },
+              "502": [
+                "upstream_error",
+              ],
+              "504": {
+                "$ref": "#/components/responses/RequestTimeout",
+              },
+            },
+            "operationId": "coingeckoPairs",
+            "response": {
+              "$ref": "#/components/schemas/CoinGeckoPairsResponse",
+            },
+          },
+        },
+        "required": {
+          "asset": [
+            "id",
+            "name",
+            "symbol",
+            "decimals",
+            "totalSupply",
+          ],
+          "block": [
+            "blockNumber",
+            "blockTimestamp",
+          ],
+          "pair": [
+            "id",
+            "dexKey",
+            "asset0Id",
+            "asset1Id",
+            "token0",
+            "token1",
+            "reserve0",
+            "reserve1",
+          ],
+          "swapEvent": [
+            "block",
+            "eventType",
+            "txnId",
+            "txnIndex",
+            "eventIndex",
+            "maker",
+            "pairId",
+            "priceNative",
+            "reserves",
+          ],
+        },
+        "undescribedComponents": [],
+      }
+    `)
+  })
+
+  test('returns the existing route-specific validation errors', async () => {
+    const app = TestApp.create({ auth: false })
+    const invalidChain = await app.request('/gecko/not-a-chain/latest-block')
+    const unsupportedChain = await app.request('/gecko/999999/latest-block')
+    const invalidAssetChain = await app.request(`/gecko/not-a-chain/assets/${pathUsd}`)
+    const invalidAsset = await app.request(`/gecko/${chainId}/assets/not-an-address`)
+    const invalidPairChain = await app.request(`/gecko/not-a-chain/pairs/0x${'11'.repeat(32)}`)
+    const invalidPair = await app.request(`/gecko/${chainId}/pairs/not-a-pair`)
+    const invalidQuery = await app.request(`/gecko/${chainId}/pairs?limit=0`)
+
+    expect(
+      await Promise.all(
+        [
+          invalidChain,
+          unsupportedChain,
+          invalidAssetChain,
+          invalidAsset,
+          invalidPairChain,
+          invalidPair,
+          invalidQuery,
+        ].map(async (response) => (await TestApp.json(response, Schema.ErrorResponse)).error.code),
+      ),
+    ).toStrictEqual([
+      'chain_id_invalid',
+      'chain_id_unsupported',
+      'chain_id_invalid',
+      'address_invalid',
+      'chain_id_invalid',
+      'pair_id_invalid',
+      'query_invalid',
+    ])
+  })
+})
+
 describe('GET /gecko/:chainId/latest-block', () => {
   test('returns the latest indexed block', async () => {
     const client = TestApp.client()