tapimo 0.13.0 → 0.15.0

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

@@ -2,12 +2,13 @@
 
 import type * as z from 'zod/mini'
 import { Value as core_Value } from 'ox'
-import { Db, Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
+import { Db, Schema } from 'tapimo/server'
 import { Addresses } from 'viem/tempo'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
+import * as Cursor from '../../../internal/Cursor.js'
 import * as Tidx from '../../../internal/Tidx.js'
 import * as Transfers from './transfers.js'
 
@@ -218,6 +219,13 @@ describe('OpenAPI', () => {
               },
             ],
             "description": "Rate provenance, or \`null\` when every valued holding was already denominated in \`currency\`.",
+            "examples": [
+              {
+                "asOf": "2026-07-20T00:00:00.000Z",
+                "basis": "nominal",
+                "source": "ecb",
+              },
+            ],
           },
         },
         "operations": {
@@ -535,28 +543,24 @@ describe('GET /transfers', () => {
       Db.postgres({
         connectionString: 'postgresql://postgres:postgres@127.0.0.1:1/none',
       })
-    const client = TestApp.client({ db, fx: { oracle: fixed } })
+    const client = TestApp.client({ auth: false, db, fx: { oracle: fixed } })
 
-    const response = await client.v1.transfers.$get(
-      {
-        query: {
-          limit: '5',
-          token: TestApp.tokenWithHolders,
-          'valuation.currency': 'USD',
-        },
+    const response = await client.v1.transfers.$get({
+      query: {
+        limit: '5',
+        token: TestApp.tokenWithHolders,
+        'valuation.currency': 'USD',
       },
-      TestApp.auth,
-    )
+    })
     const body = await TestApp.json(response, Transfers.schema.getTransfers.Response)
 
     expect(response.status).toBe(200)
     expect(body.data.length).toBeGreaterThan(0)
     for (const entry of body.data) expect(entry.sourceAmount.valuation).toBeNull()
 
-    const emptyResponse = await client.v1.transfers.$get(
-      { query: { limit: '5', token: `0x${'11'.repeat(20)}` } },
-      TestApp.auth,
-    )
+    const emptyResponse = await client.v1.transfers.$get({
+      query: { limit: '5', token: `0x${'11'.repeat(20)}` },
+    })
     const empty = await TestApp.json(emptyResponse, Transfers.schema.getTransfers.Response)
     expect(emptyResponse.status).toBe(200)
     expect(empty.data).toMatchInlineSnapshot(`[]`)
@@ -564,16 +568,13 @@ describe('GET /transfers', () => {
       true,
     )
 
-    const unsupportedResponse = await client.v1.transfers.$get(
-      {
-        query: {
-          limit: '5',
-          token: TestApp.tokenWithHolders,
-          'valuation.currency': 'JPY',
-        },
+    const unsupportedResponse = await client.v1.transfers.$get({
+      query: {
+        limit: '5',
+        token: TestApp.tokenWithHolders,
+        'valuation.currency': 'JPY',
       },
-      TestApp.auth,
-    )
+    })
     const unsupported = await TestApp.json(unsupportedResponse, Schema.ErrorResponse)
     expect(unsupportedResponse.status).toBe(400)
     expect(unsupported.error.code).toBe('query_invalid')
@@ -1622,6 +1623,37 @@ describe('collate', () => {
   })
 })
 
+describe('decodeTransferCursor', () => {
+  test('accepts only continuation offsets within the bounded page window', () => {
+    const position = [123, 4]
+    expect([
+      Transfers.decodeTransferCursor({ limit: 5, token: Cursor.encode(position) }),
+      Transfers.decodeTransferCursor({ limit: 5, token: Cursor.encode([...position, 495]) }),
+      Transfers.decodeTransferCursor({ limit: 5, token: Cursor.encode([...position, 496]) }),
+      Transfers.decodeTransferCursor({ limit: 5, token: Cursor.encode([...position, 10_000]) }),
+    ]).toMatchInlineSnapshot(`
+      [
+        {
+          "offset": 0,
+          "position": [
+            123,
+            4,
+          ],
+        },
+        {
+          "offset": 495,
+          "position": [
+            123,
+            4,
+          ],
+        },
+        undefined,
+        undefined,
+      ]
+    `)
+  })
+})
+
 describe('foldCount', () => {
   const swapper = `0x${'11'.repeat(20)}`
   const recipient = `0x${'22'.repeat(20)}`

package/src/apps/data/routes/transfers.ts

@@ -712,7 +712,7 @@ export function query(c: Context<App.Environment>, options: query.Options) {
   const { chainId, timing, ...rest } = options
   const store = c.get('store')
   const tidx = c.get('getTidx')(chainId)
-  const cursor = decodeTransferCursor(options.cursor)
+  const cursor = decodeTransferCursor({ limit: options.limit, token: options.cursor })
 
   return Timing.time(c, timing, () =>
     Store.memoize(
@@ -786,7 +786,7 @@ export async function scan(deps: scan.Deps, options: scan.Options): Promise<scan
   // Keyset pagination: anchor the page below the previous row's `(block, log_idx)`
   // position instead of a numeric offset, so rows arriving at the head can't
   // shift items across pages. A malformed cursor falls back to the head page.
-  const cursor = decodeTransferCursor(options.cursor)
+  const cursor = decodeTransferCursor({ limit, token: options.cursor })
   // Bounded positional lane (exclusive with `cursor` at the schema): page 1 is
   // the head page, so it shares the head's SQL and cache entries; deeper pages
   // translate to a SQL OFFSET of `(page - 1) * limit` rows.
@@ -1393,17 +1393,28 @@ export declare namespace scan {
 }
 
 /** Decodes ordinary transfer cursors and capped positional continuations. */
-function decodeTransferCursor(token: string | undefined): decodeTransferCursor.Result | undefined {
-  if (token === undefined) return undefined
-  const position = Cursor.decode(token, ['int', 'int'])
+export function decodeTransferCursor(
+  options: decodeTransferCursor.Options,
+): decodeTransferCursor.Result | undefined {
+  if (options.token === undefined) return undefined
+  const position = Cursor.decode(options.token, ['int', 'int'])
   if (position) return { offset: 0, position: position as [blockNumber: number, logIndex: number] }
-  const continuation = Cursor.decode(token, ['int', 'int', 'int'])
+  const continuation = Cursor.decode(options.token, ['int', 'int', 'int'])
   if (!continuation) return undefined
   const [blockNumber, logIndex, offset] = continuation as [number, number, number]
-  return { offset: Math.max(0, offset), position: [blockNumber, logIndex] }
+  if (offset < 0 || offset + options.limit > Schema.maxPageWindow) return undefined
+  return { offset, position: [blockNumber, logIndex] }
 }
 
-declare namespace decodeTransferCursor {
+export declare namespace decodeTransferCursor {
+  /** Cursor token and requested page size. */
+  type Options = {
+    /** Requested response page size. */
+    limit: number
+    /** Opaque transfer cursor. */
+    token?: string | undefined
+  }
+
   /** Decoded raw position plus any filtered rows still to skip. */
   type Result = {
     offset: number

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

@@ -2,8 +2,8 @@
 
 import * as fs from 'node:fs'
 import { Value as core_Value } from 'ox'
-import { Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
+import { Schema } from 'tapimo/server'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { Actions } from 'viem/tempo'
 

package/src/apps/data/routes/verified-tokens.test.ts

@@ -1,8 +1,32 @@
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
+import * as Db from '../../../db/Db.js'
+import * as Schema from '../../../internal/Schema.js'
 import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
 import * as Verified from './verified-tokens.js'
 
+type JsonSchema = {
+  $ref?: string
+  description?: string
+  enum?: readonly string[]
+  examples?: readonly unknown[]
+  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 }>
+}
+
 /** Reader key for the data routes. */
 const reader = {
   id: 'key_reader',
@@ -37,7 +61,328 @@ async function seeded() {
   })
 }
 
+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 verified-token contracts', async () => {
+    const app = TestApp.create({ auth: false })
+    const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+    const operations = {
+      currencies: spec.paths['/v1/verified-tokens/currencies']?.get,
+      detail: spec.paths['/v1/verified-tokens/{address}']?.get,
+      list: spec.paths['/v1/verified-tokens']?.get,
+    }
+    if (Object.values(operations).some((operation) => !operation))
+      throw new Error('Missing verified-token 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 verified-token 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 token = component(spec, 'VerifiedToken')
+    const list = component(spec, 'VerifiedTokenList')
+    const currencies = component(spec, 'VerifiedTokenCurrencyList')
+
+    expect({
+      components: {
+        currencies: {
+          dataExamples: currencies.properties?.['data']?.examples,
+          description: currencies.description,
+          required: currencies.required,
+        },
+        list: {
+          dataExamples: list.properties?.['data']?.examples,
+          description: list.description,
+          item: list.properties?.['data']?.items,
+          required: list.required,
+        },
+        token: {
+          description: token.description,
+          required: token.required,
+        },
+      },
+      operations: Object.fromEntries(
+        Object.entries(operations).map(([name, operation]) => [name, summarize(operation)]),
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "components": {
+          "currencies": {
+            "dataExamples": [
+              [
+                "USD",
+              ],
+            ],
+            "description": "The distinct currencies present in a chain’s verified token list.",
+            "required": [
+              "data",
+            ],
+          },
+          "list": {
+            "dataExamples": [
+              [
+                {
+                  "address": "0x20c0000000000000000000008f5425160ebe5525",
+                  "currency": "USD",
+                  "decimals": 6,
+                  "id": "0x20c0000000000000000000008f5425160ebe5525",
+                  "name": "USD Coin",
+                  "symbol": "USDC",
+                },
+              ],
+            ],
+            "description": "A non-paginated list of curated, verified TIP-20 tokens.",
+            "item": {
+              "$ref": "#/components/schemas/VerifiedToken",
+              "examples": [
+                {
+                  "address": "0x20c0000000000000000000008f5425160ebe5525",
+                  "currency": "USD",
+                  "decimals": 6,
+                  "id": "0x20c0000000000000000000008f5425160ebe5525",
+                  "name": "USD Coin",
+                  "symbol": "USDC",
+                },
+              ],
+            },
+            "required": [
+              "data",
+            ],
+          },
+          "token": {
+            "description": "One curated, verified TIP-20 token that wallets and apps can present as trusted.",
+            "required": [
+              "address",
+              "currency",
+              "decimals",
+              "name",
+              "symbol",
+              "id",
+            ],
+          },
+        },
+        "operations": {
+          "currencies": {
+            "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": "getVerifiedTokenCurrencies",
+            "response": {
+              "$ref": "#/components/schemas/VerifiedTokenCurrencyList",
+            },
+          },
+          "detail": {
+            "errors": {
+              "400": [
+                "address_invalid",
+                "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": [
+                "verified_token_not_found",
+              ],
+              "429": {
+                "$ref": "#/components/responses/RateLimited",
+              },
+              "500": {
+                "$ref": "#/components/responses/InternalError",
+              },
+              "502": [
+                "upstream_error",
+              ],
+              "504": {
+                "$ref": "#/components/responses/RequestTimeout",
+              },
+            },
+            "operationId": "getVerifiedToken",
+            "response": {
+              "$ref": "#/components/schemas/VerifiedToken",
+            },
+          },
+          "list": {
+            "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": "listVerifiedTokens",
+            "response": {
+              "$ref": "#/components/schemas/VerifiedTokenList",
+            },
+          },
+        },
+      }
+    `)
+  })
+
+  test('returns the existing route-specific validation errors', async () => {
+    const app = TestApp.create({ auth: false })
+    const invalidListChain = await app.request('/v1/verified-tokens?chainId=not-a-chain')
+    const unsupportedListChain = await app.request('/v1/verified-tokens?chainId=999999')
+    const invalidListQuery = await app.request('/v1/verified-tokens?unknown=true')
+    const invalidCurrenciesChain = await app.request(
+      '/v1/verified-tokens/currencies?chainId=not-a-chain',
+    )
+    const unsupportedCurrenciesChain = await app.request(
+      '/v1/verified-tokens/currencies?chainId=999999',
+    )
+    const invalidCurrenciesQuery = await app.request('/v1/verified-tokens/currencies?unknown=true')
+    const invalidAddress = await app.request('/v1/verified-tokens/not-an-address')
+    const invalidDetailChain = await app.request(
+      `/v1/verified-tokens/${unknownAddress}?chainId=not-a-chain`,
+    )
+    const unsupportedDetailChain = await app.request(
+      `/v1/verified-tokens/${unknownAddress}?chainId=999999`,
+    )
+    const invalidDetailQuery = await app.request(
+      `/v1/verified-tokens/${unknownAddress}?unknown=true`,
+    )
+
+    expect(
+      await Promise.all(
+        [
+          invalidListChain,
+          unsupportedListChain,
+          invalidListQuery,
+          invalidCurrenciesChain,
+          unsupportedCurrenciesChain,
+          invalidCurrenciesQuery,
+          invalidAddress,
+          invalidDetailChain,
+          unsupportedDetailChain,
+          invalidDetailQuery,
+        ].map(async (response) => (await TestApp.json(response, Schema.ErrorResponse)).error.code),
+      ),
+    ).toStrictEqual([
+      'chain_id_invalid',
+      'chain_id_unsupported',
+      'query_invalid',
+      'chain_id_invalid',
+      'chain_id_unsupported',
+      'query_invalid',
+      'address_invalid',
+      'chain_id_invalid',
+      'chain_id_unsupported',
+      'query_invalid',
+    ])
+  })
+})
+
 describe('GET /verified-tokens', () => {
+  test('maps cold cache-key store failures to the upstream error contract', async () => {
+    const app = TestApp.create({
+      auth: false,
+      db: Db.postgres({ connectionString: 'postgresql://postgres:postgres@127.0.0.1:1/none' }),
+      verifiedTokens: { refreshMs: 0 },
+    })
+
+    const response = await app.request('/v1/verified-tokens')
+    expect(response.status).toBe(502)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: { code: 'upstream_error' },
+    })
+    expect(response.headers.get('cache-control')).toBe('no-store')
+  })
+
   test('returns the verified list', async () => {
     const response = await (await seeded()).v1['verified-tokens'].$get({ query: {} }, as(reader))
     expect(response.status).toBe(200)