tapimo 0.5.3 → 0.7.0

package/src/analytics/Analytics.test.ts

@@ -36,6 +36,9 @@ const row = {
   rate_limit_scope: null,
   request_id: 'req-1',
   route: '/v1/transactions',
+  rpc_error_code: null,
+  rpc_error_count: 0,
+  rpc_error_data_code: null,
   service: 'api',
   status: 200,
   timestamp: '2026-01-01 00:00:00.000',
@@ -211,6 +214,9 @@ describe('createQueueSink', () => {
       rate_limit_scope: row.rate_limit_scope,
       request_id: row.request_id,
       route: row.route,
+      rpc_error_code: row.rpc_error_code,
+      rpc_error_count: row.rpc_error_count,
+      rpc_error_data_code: row.rpc_error_data_code,
       service: row.service,
       status: row.status,
       timestamp: '<timestamp>',
@@ -229,6 +235,9 @@ describe('createQueueSink', () => {
         "rate_limit_scope": null,
         "request_id": "req-1",
         "route": "/v1/transactions",
+        "rpc_error_code": null,
+        "rpc_error_count": 0,
+        "rpc_error_data_code": null,
         "service": "api",
         "status": 200,
         "timestamp": "<timestamp>",
@@ -272,6 +281,24 @@ describe('createQueueSink', () => {
     })
   })
 
+  test('records JSON-RPC error metadata', async () => {
+    const send = vi.fn<(message: Analytics.Event) => Promise<void>>().mockResolvedValue(undefined)
+    const sink = Analytics.createQueueSink({ send })(context)
+
+    await sink({
+      ...entry,
+      level: 'warn',
+      rpc: { code: -32602, dataCode: 'billing_required', errors: 2 },
+    })
+
+    expect(send.mock.calls[0]![0]).toMatchObject({
+      rpc_error_code: -32602,
+      rpc_error_count: 2,
+      rpc_error_data_code: 'billing_required',
+      status: 200,
+    })
+  })
+
   test('rethrows when the retry also fails', async () => {
     const send = vi
       .fn<(message: Analytics.Event) => Promise<void>>()
@@ -399,6 +426,7 @@ describe('readProjectUsage', () => {
     expect(query).toContain(`key_environment = 'sandbox'`)
     expect(query).not.toContain('key_id IN')
     expect(query).toContain('LIMIT 100')
+    expect(query).toContain('status >= 400 OR rpc_error_count > 0')
     expect(new URL(String(fetch.mock.calls[0]![0])).searchParams.get('query')).toBeNull()
     expect(usage).toMatchObject({
       from: '2026-01-01T00:00:00.000Z',
@@ -408,6 +436,29 @@ describe('readProjectUsage', () => {
     })
   })
 
+  test('includes JSON-RPC failures in the error breakdown', async () => {
+    const fetch = vi.fn<typeof globalThis.fetch>().mockResolvedValue(
+      new Response(JSON.stringify({ data: [{ code: 'billing_required', requests: '2' }] }), {
+        status: 200,
+      }),
+    )
+    vi.stubGlobal('fetch', fetch)
+
+    const breakdown = await RequestEvents.readErrorBreakdown(Analytics.clickhouse(clickHouse), {
+      attributions: [{ projectId: 'prj_1' }],
+      from: '2026-01-01T00:00:00.000Z',
+      interval: 'day',
+      orgId: 'org_1',
+      to: '2026-01-02T00:00:00.000Z',
+    })
+
+    expect(fetch.mock.calls[0]![1]?.body).toEqual(expect.stringContaining('rpc_error_data_code'))
+    expect(fetch.mock.calls[0]![1]?.body).toEqual(
+      expect.stringContaining('status >= 400 OR rpc_error_count > 0'),
+    )
+    expect(breakdown).toEqual([{ code: 'billing_required', requests: 2 }])
+  })
+
   test('keeps legacy rows scoped to project keys without global org filtering', async () => {
     const fetch = vi
       .fn<typeof globalThis.fetch>()
@@ -525,3 +576,35 @@ describe('readProjectUsage', () => {
     })
   })
 })
+
+describe('readLastUsedAt', () => {
+  test('returns the latest request timestamp for each requested key', async () => {
+    const fetch = vi.fn<typeof globalThis.fetch>().mockImplementation(async (_url, init) => {
+      const sql = init?.body
+      if (typeof sql !== 'string') throw new Error('Expected a SQL request body.')
+      expect(sql).toContain("key_id IN ('key_1', 'key_2')")
+      expect(sql).toContain('max(timestamp)')
+      return new Response(
+        JSON.stringify({
+          data: [{ key_id: 'key_1', lastUsedAt: '2026-07-21T12:34:56.000Z' }],
+        }),
+        { status: 200 },
+      )
+    })
+    vi.stubGlobal('fetch', fetch)
+
+    await expect(
+      RequestEvents.readLastUsedAt(Analytics.clickhouse(clickHouse), ['key_1', 'key_2']),
+    ).resolves.toEqual([{ apiKeyId: 'key_1', lastUsedAt: '2026-07-21T12:34:56.000Z' }])
+  })
+
+  test('skips the analytics query when no keys are requested', async () => {
+    const fetch = vi.fn<typeof globalThis.fetch>()
+    vi.stubGlobal('fetch', fetch)
+
+    await expect(
+      RequestEvents.readLastUsedAt(Analytics.clickhouse(clickHouse), []),
+    ).resolves.toEqual([])
+    expect(fetch).not.toHaveBeenCalled()
+  })
+})

package/src/analytics/Analytics.ts

@@ -131,6 +131,9 @@ export const migrations: readonly Migration[] = [
         project_id Nullable(String),
         rate_limit_scope Nullable(String),
         error_code Nullable(String),
+        rpc_error_code Nullable(Int32),
+        rpc_error_data_code Nullable(String),
+        rpc_error_count UInt16 DEFAULT 0,
         request_id Nullable(String),
         billing_active Nullable(UInt8)
       )
@@ -156,6 +159,23 @@ export const migrations: readonly Migration[] = [
         ADD COLUMN IF NOT EXISTS billing_active Nullable(UInt8)
     `,
   },
+  {
+    name: '0003_request_events_rpc_errors',
+    // Patches tables created before RPC columns entered the baseline. Fresh
+    // tables include them, allowing scoped preview users without ALTER to skip.
+    guard: `
+      SELECT toUInt8(count() = 3) FROM system.columns
+      WHERE database = currentDatabase()
+        AND table = 'request_events'
+        AND name IN ('rpc_error_code', 'rpc_error_data_code', 'rpc_error_count')
+    `,
+    sql: `
+      ALTER TABLE request_events
+        ADD COLUMN IF NOT EXISTS rpc_error_code Nullable(Int32),
+        ADD COLUMN IF NOT EXISTS rpc_error_data_code Nullable(String),
+        ADD COLUMN IF NOT EXISTS rpc_error_count UInt16 DEFAULT 0
+    `,
+  },
 ]
 
 /**

package/src/analytics/tables/requestEvents.ts

@@ -30,6 +30,12 @@ export type Table = {
   principal_type: 'api_key' | 'public' | 'session' | 'super_admin' | 'unknown'
   /** Rate-limit bucket scope, when a rate limit was applied. */
   rate_limit_scope: string | null
+  /** Numeric JSON-RPC error code when every failed response shares one code. */
+  rpc_error_code: number | null
+  /** Stable application error code from JSON-RPC `error.data.code`. */
+  rpc_error_data_code: string | null
+  /** Number of failed JSON-RPC responses in the request. */
+  rpc_error_count: number
   /** Stable per-request id (`entry.requestId`); dedups the billing count via `uniqExact`. */
   request_id: string | null
   /** Bounded matched route pattern. */
@@ -79,6 +85,14 @@ export type KeyBreakdown = {
   requests: number
 }
 
+/** Latest authenticated request timestamp for one API key. */
+export type LastUsedAt = {
+  /** API key id (`key_…`). */
+  apiKeyId: string
+  /** Latest request completion timestamp (ISO 8601). */
+  lastUsedAt: string
+}
+
 /** Time bucket size for the usage series. */
 export type Interval = 'day' | 'hour'
 
@@ -227,6 +241,32 @@ export declare namespace insertMessages {
   }
 }
 
+/**
+ * Reads the latest authenticated request timestamp for each requested API key.
+ * Keys with no request events are omitted.
+ */
+export async function readLastUsedAt(
+  analytics: Analytics.Analytics,
+  apiKeyIds: readonly string[],
+): Promise<LastUsedAt[]> {
+  if (apiKeyIds.length === 0) return []
+  const rows = await analytics.query<LastUsedAtRow>(
+    `
+      SELECT
+        key_id,
+        formatDateTime(max(timestamp), '%Y-%m-%dT%H:%i:%S.000Z', 'UTC') AS lastUsedAt
+      FROM ${table}
+      WHERE principal_type = 'api_key'
+        AND key_id IN (${apiKeyIds.map(literal).join(', ')})
+      GROUP BY key_id
+    `,
+  )
+  return rows.map((row) => ({
+    apiKeyId: String(row.key_id),
+    lastUsedAt: String(row.lastUsedAt),
+  }))
+}
+
 /**
  * Reads request usage for one project from the `request_events` table.
  *
@@ -247,7 +287,7 @@ export async function readProjectUsage(
         SELECT
           key_id,
           count() AS requests,
-          countIf(status >= 400) AS errors,
+          countIf(status >= 400 OR rpc_error_count > 0) AS errors,
           ${average} AS averageDurationMs
         FROM ${table}
         WHERE ${where} AND key_id IS NOT NULL
@@ -261,7 +301,7 @@ export async function readProjectUsage(
         SELECT
           route,
           count() AS requests,
-          countIf(status >= 400) AS errors,
+          countIf(status >= 400 OR rpc_error_count > 0) AS errors,
           ${average} AS averageDurationMs
         FROM ${table}
         WHERE ${where}
@@ -286,7 +326,7 @@ export async function readProjectUsage(
         SELECT
           formatDateTime(${bucket}, '%Y-%m-%dT%H:%i:%S.000Z', 'UTC') AS time,
           count() AS requests,
-          countIf(status >= 400) AS errors
+          countIf(status >= 400 OR rpc_error_count > 0) AS errors
         FROM ${table}
         WHERE ${where}
         GROUP BY ${bucket}
@@ -297,7 +337,7 @@ export async function readProjectUsage(
       `
         SELECT
           count() AS requests,
-          countIf(status >= 400) AS errors,
+          countIf(status >= 400 OR rpc_error_count > 0) AS errors,
           ${average} AS averageDurationMs
         FROM ${table}
         WHERE ${where}
@@ -347,11 +387,16 @@ export async function readErrorBreakdown(
   const rows = await analytics.query<ErrorRow>(
     `
       SELECT
-        coalesce(error_code, 'unknown') AS code,
+        coalesce(
+          error_code,
+          rpc_error_data_code,
+          if(rpc_error_count > 0 AND rpc_error_code IS NOT NULL, concat('rpc_', toString(rpc_error_code)), NULL),
+          if(rpc_error_count > 0, 'rpc_multiple', 'unknown')
+        ) AS code,
         count() AS requests
       FROM ${table}
-      WHERE ${usageWhere(options)} AND status >= 400
-      GROUP BY error_code
+      WHERE ${usageWhere(options)} AND (status >= 400 OR rpc_error_count > 0)
+      GROUP BY code
       ORDER BY requests DESC, code ASC
       LIMIT 25
     `,
@@ -434,6 +479,11 @@ type KeyRow = {
   requests: number | string
 }
 
+type LastUsedAtRow = {
+  key_id: string
+  lastUsedAt: string
+}
+
 type ErrorRow = {
   code: string
   requests: number | string
@@ -480,6 +530,9 @@ function event(entry: Log.Entry, context: Metrics.cloudflare.Context): Table {
     rate_limit_scope: entry.rateLimit?.scope ?? null,
     request_id: entry.requestId ?? null,
     route: entry.route,
+    rpc_error_code: entry.rpc?.code ?? null,
+    rpc_error_count: entry.rpc?.errors ?? 0,
+    rpc_error_data_code: entry.rpc?.dataCode ?? null,
     service: context.service ?? 'unknown',
     status: entry.status,
     timestamp: timestamp(),

package/src/apps/composition.test.ts

@@ -1,5 +1,5 @@
 import { App, Store } from 'tapimo'
-import { data, management, relay } from 'tapimo/apps'
+import { data, management, mpp, relay } from 'tapimo/apps'
 import { Hono } from 'hono'
 import { describeRoute } from 'hono-openapi'
 import * as TestApp from '../../test/App.js'
@@ -190,7 +190,7 @@ describe('data()', () => {
 })
 
 describe('relay()', () => {
-  test('mounts the relay after data() and stays out of the document', async () => {
+  test('mounts the relay after data() without documenting RPC routes', async () => {
     const composed = App.create({ db: TestApp.database() }).route('/', data()).route('/', relay())
 
     // Mounted but default-closed and hidden: unauthenticated requests are
@@ -209,6 +209,15 @@ describe('relay()', () => {
   })
 })
 
+describe('mpp()', () => {
+  test('mounts documented MPP routes independently', async () => {
+    const app = App.create({ db: TestApp.database() }).route('/', mpp())
+
+    expect((await paths(app)).some((path) => path.startsWith('/v1/mpp'))).toBe(true)
+    expect((await app.request('/rpc/relay')).status).toBe(404)
+  })
+})
+
 describe('management()', () => {
   test('mounts management routes and omits data routes', async () => {
     const app = App.create({

package/src/apps/data/App.test.ts

@@ -254,7 +254,7 @@ describe('zone chain gate', () => {
     for (const path of [
       `/v1/tokens?chainId=${zone}`,
       `/v1/addresses/0x0000000000000000000000000000000000000001/activities?chainId=${zone}`,
-      `/v1/transfers?chainId=${zone}&include=token`,
+      `/v1/transfers?chainId=${zone}&include=token.verified`,
     ]) {
       const response = await app.request(path)
       const body = (await response.json()) as { error: { code: string; message: string } }

package/src/apps/data/App.ts

@@ -14,6 +14,7 @@ import * as Tidx from '../../internal/Tidx.js'
 import * as Viem from '../../internal/Viem.js'
 import * as Scope from '../../Scope.js'
 import * as Metadata from '../metadata.js'
+import type * as FxOracle from './FxOracle.js'
 
 import { transactions as transactionActivities } from './routes/activities.js'
 import { addresses } from './routes/addresses.js'
@@ -42,6 +43,12 @@ import { schema as webhookSchema, webhooks } from './routes/webhooks.js'
  */
 export function data(options: data.Options = {}) {
   const { assets, tidx } = options
+  const webhook =
+    options.webhook === false
+      ? undefined
+      : (options.webhook ?? {
+          supportedChainIds: [Viem.chainId.mainnet, Viem.chainId.testnet],
+        })
 
   // Zone endpoints are explicit trust boundaries; the API never derives them.
   const zones = new Map((options.zones ?? []).map((zone) => [zone.chainId, zone]))
@@ -66,7 +73,7 @@ export function data(options: data.Options = {}) {
       c.set('supportedChainIds', supportedChainIds)
       c.set('tidx', tidx)
       c.set('verifiedTokens', options.verifiedTokens === false ? undefined : (options.verifiedTokens ?? {})) // prettier-ignore
-      c.set('webhook', options.webhook === false ? undefined : (options.webhook ?? {}))
+      c.set('webhook', webhook)
       c.set('zones', zones)
       await next()
     })
@@ -158,18 +165,18 @@ export function data(options: data.Options = {}) {
         'Content-Type': asset.contentType,
       })
     })
-    .route('/', addresses())
+    .route('/', addresses({ fx: options.fx }))
     .route('/', blocks())
-    .route('/', exchanges())
+    .route('/', exchanges({ fx: options.fx }))
     .route('/', feeAmm())
     .route('/', funding(options.funding))
     .route('/', indexer())
-    .route('/', receipts())
+    .route('/', receipts({ fx: options.fx }))
     .route('/', tokenlist())
     .route('/', tokens())
     .route('/', transactions())
-    .route('/', transactionActivities())
-    .route('/', transfers())
+    .route('/', transactionActivities({ fx: options.fx }))
+    .route('/', transfers({ fx: options.fx }))
     .route('/', verifiedTokens())
     .route('/', webhooks({ enabled: options.webhook !== false }))
     .route('/', rpc())
@@ -206,6 +213,8 @@ export declare namespace data {
     assets?: Assets.Assets | undefined
     /** Funding quote provider configuration. */
     funding?: funding.Options | undefined
+    /** FX configuration for the valuation endpoint. */
+    fx?: Fx | undefined
     /** TIDX query client options. */
     tidx?: Tidx.getClient.Tidx | undefined
     /** Verified-token feature configuration. Enabled by default (token rows live in `db`; empty until published); pass `false` to always serve an empty verified list. */
@@ -219,6 +228,12 @@ export declare namespace data {
     zones?: readonly Zone[] | undefined
   }
 
+  /** FX configuration for the valuation endpoint. */
+  type Fx = {
+    /** FX rate oracle backing currency conversion. Defaults to the ECB daily reference rates (`FxOracle.ecb()`). */
+    oracle?: FxOracle.Oracle | undefined
+  }
+
   /** One zone chain served by this deployment. */
   type Zone = {
     /** Zone chain id. Consumer-supplied literal; the API never derives zone chain ids. */
@@ -238,14 +253,7 @@ export declare namespace data {
   }
 
   /** Webhook feature configuration. */
-  type Webhook = {
-    /**
-     * Maximum active subscriptions per owner; creation is rejected with
-     * `403 limit_exceeded` once reached. Defaults to 100, bounding the spam/SSRF
-     * and delivery-cost surface per owner.
-     */
-    maxPerOwner?: number | undefined
-  }
+  type Webhook = App.Webhook
 }
 
 function resolveChainSelector(options: {