tapimo 0.4.0 → 0.4.3

package/src/analytics/Analytics.ts

@@ -8,6 +8,31 @@ export type BillableCount = RequestEvents.BillableCount
 /** Options for {@link readBillableRequestCounts}. */
 export type BillableCountsOptions = RequestEvents.BillableCountsOptions
 
+/** One organization's request usage and error breakdown. */
+export type ProjectUsage = RequestEvents.ProjectUsage
+
+/** Options for reading one organization's request usage. */
+export type ProjectUsageOptions = RequestEvents.ProjectUsageOptions
+
+/** API errors grouped by their stable error code. */
+export type ErrorBreakdown = RequestEvents.ErrorBreakdown
+
+/** Reads stable API error-code counts for one organization attribution window. */
+export function readErrorBreakdown(
+  source: Source,
+  options: ProjectUsageOptions,
+): Promise<ErrorBreakdown[]> {
+  return RequestEvents.readErrorBreakdown(get(source), options)
+}
+
+/** Reads request usage for an organization and optional attribution terms. */
+export function readProjectUsage(
+  source: Source,
+  options: ProjectUsageOptions,
+): Promise<ProjectUsage> {
+  return RequestEvents.readProjectUsage(get(source), options)
+}
+
 /**
  * Reads deduped billable request counts grouped by `(org, UTC hour)` from
  * `request_events` — the request-metered billing source. Resolves the source

package/src/analytics/tables/requestEvents.ts

@@ -59,6 +59,14 @@ export type Attribution = {
 /** API-key environment for request usage. */
 export type Environment = 'production' | 'sandbox'
 
+/** API errors grouped by their stable error code. */
+export type ErrorBreakdown = {
+  /** Stable API error code, or `unknown` when none was recorded. */
+  code: string
+  /** Requests returning this error. */
+  requests: number
+}
+
 /** API key usage grouped for one project. */
 export type KeyBreakdown = {
   /** API key id (`key_…`). */
@@ -331,6 +339,26 @@ export async function readProjectUsage(
   }
 }
 
+/** Reads stable API error-code counts for one organization attribution window. */
+export async function readErrorBreakdown(
+  analytics: Analytics.Analytics,
+  options: ProjectUsageOptions,
+): Promise<ErrorBreakdown[]> {
+  const rows = await analytics.query<ErrorRow>(
+    `
+      SELECT
+        coalesce(error_code, 'unknown') AS code,
+        count() AS requests
+      FROM ${table}
+      WHERE ${usageWhere(options)} AND status >= 400
+      GROUP BY error_code
+      ORDER BY requests DESC, code ASC
+      LIMIT 25
+    `,
+  )
+  return rows.map((row) => ({ code: String(row.code), requests: number(row.requests) }))
+}
+
 /** One org's deduped billable request count for a single UTC hour. */
 export type BillableCount = {
   /** UTC hour start (ISO 8601). */
@@ -406,6 +434,11 @@ type KeyRow = {
   requests: number | string
 }
 
+type ErrorRow = {
+  code: string
+  requests: number | string
+}
+
 type RouteRow = {
   averageDurationMs: number | string
   errors: number | string

package/src/apps/composition.test.ts

@@ -1,5 +1,7 @@
 import { App, Store } from 'tapimo'
 import { data, management, relay } from 'tapimo/apps'
+import { Hono } from 'hono'
+import { describeRoute } from 'hono-openapi'
 import * as TestApp from '../../test/App.js'
 
 // Each test mounts one group and asserts its routes exist while omitted groups
@@ -10,7 +12,10 @@ import * as TestApp from '../../test/App.js'
 async function document(app: { request: (path: string) => Promise<Response> | Response }) {
   const res = await app.request('/openapi.json')
   return (await res.json()) as {
+    components: { securitySchemes: Record<string, unknown> }
     paths: Record<string, unknown>
+    tags: readonly { description: string; name: string }[]
+    webhooks?: Record<string, unknown> | undefined
     'x-tagGroups'?: readonly { name: string; tags: readonly string[] }[] | undefined
   }
 }
@@ -20,6 +25,77 @@ async function paths(app: { request: (path: string) => Promise<Response> | Respo
   return Object.keys((await document(app)).paths)
 }
 
+describe('App.from()', () => {
+  test('contributes external route-group metadata', async () => {
+    const group = new Hono().get(
+      '/v1/external/webhooks',
+      describeRoute({
+        responses: { 200: { description: 'External webhook status.' } },
+        summary: 'Get webhook status',
+        tags: ['External'],
+      }),
+      (c) => c.json({ status: 'ok' }, 200),
+    )
+    const external = App.from(group, {
+      docs: ({ spec }) =>
+        new Hono().get('/external-docs', async (c) => c.json({ paths: (await spec()).paths })),
+      securitySchemes: {
+        externalKey: { in: 'header', name: 'external-key', type: 'apiKey' },
+      },
+      tags: [{ description: 'Externally defined routes.', name: 'External' }],
+      webhooks: () => ({ externalEvent: { post: { responses: { 200: { description: 'OK' } } } } }),
+      'x-tagGroups': [{ name: 'External API', tags: ['External'] }],
+    })
+    expectTypeOf(external).toEqualTypeOf<typeof group>()
+
+    const app = App.create({ auth: false, db: TestApp.database() }).route('/', external)
+    const spec = await document(app)
+
+    expect({
+      securityScheme: spec.components.securitySchemes['externalKey'],
+      tags: spec.tags,
+      tagGroups: spec['x-tagGroups'],
+      webhooks: spec.webhooks,
+    }).toMatchInlineSnapshot(`
+      {
+        "securityScheme": {
+          "in": "header",
+          "name": "external-key",
+          "type": "apiKey",
+        },
+        "tagGroups": [
+          {
+            "name": "External API",
+            "tags": [
+              "External",
+            ],
+          },
+        ],
+        "tags": [
+          {
+            "description": "Externally defined routes.",
+            "name": "External",
+          },
+        ],
+        "webhooks": {
+          "externalEvent": {
+            "post": {
+              "responses": {
+                "200": {
+                  "description": "OK",
+                },
+              },
+            },
+          },
+        },
+      }
+    `)
+
+    const docs = await app.request('/external-docs')
+    expect((await docs.json()).paths['/v1/external/webhooks']).toBeDefined()
+  })
+})
+
 describe('data()', () => {
   test('mounts data routes and omits management routes', async () => {
     const app = App.create({ db: TestApp.database() }).route('/', data())
@@ -42,13 +118,17 @@ describe('relay()', () => {
 
     // Mounted but default-closed and hidden: unauthenticated requests are
     // refused, and the path never appears in the OpenAPI document.
-    const mounted = await composed.request('/rpc/relay')
-    expect(mounted.status).toBe(401)
+    const relayMounted = await composed.request('/rpc/relay')
+    const sponsorMounted = await composed.request('/rpc/sponsor')
+    expect(relayMounted.status).toBe(401)
+    expect(sponsorMounted.status).toBe(401)
     expect((await paths(composed)).some((path) => path.startsWith('/rpc/relay'))).toBe(false)
+    expect((await paths(composed)).some((path) => path.startsWith('/rpc/sponsor'))).toBe(false)
 
     // Without the relay group, the data group no longer serves the path.
     const dataOnly = App.create({ db: TestApp.database() }).route('/', data())
     expect((await dataOnly.request('/rpc/relay')).status).toBe(404)
+    expect((await dataOnly.request('/rpc/sponsor')).status).toBe(404)
   })
 })
 

package/src/apps/data/App.ts

@@ -87,7 +87,11 @@ export function data(options: data.Options = {}) {
     // Reject a well-formed but unsupported `chainId` before it reaches an
     // upstream, which would otherwise return an opaque `upstream_error`.
     .use('*', async (c, next) => {
-      const raw = c.req.query('chainId') ?? c.req.query('chain_id')
+      const raw = resolveChainSelector({
+        basePath: c.get('basePath') ?? '',
+        path: c.req.path,
+        query: c.req.query('chainId') ?? c.req.query('chain_id'),
+      })
       if (raw === undefined) return next()
       // Only reject a well-formed-but-unsupported chain here; malformed values
       // (e.g. `abc`, `0`) fall through to the route's own query validation.
@@ -101,13 +105,18 @@ export function data(options: data.Options = {}) {
     // `chainId`. The relay resolves its chain from the request body, not the
     // query, so it is skipped and enforces the rule in its sponsor validation.
     .use('*', async (c, next) => {
-      const relay = Path.join(c.get('basePath') ?? '', 'rpc/relay')
+      const rpc = Path.join(c.get('basePath') ?? '', 'rpc')
+      const relay = Path.join(rpc, 'relay')
       if (c.req.path === relay || c.req.path.startsWith(`${relay}/`)) return next()
 
       const principal = Auth.getPrincipal(c)
       if (principal?.type !== 'api_key' || principal.environment !== 'sandbox') return next()
 
-      const raw = c.req.query('chainId') ?? c.req.query('chain_id')
+      const raw = resolveChainSelector({
+        basePath: c.get('basePath') ?? '',
+        path: c.req.path,
+        query: c.req.query('chainId') ?? c.req.query('chain_id'),
+      })
       // Absent falls back to the group default (mainnet); a malformed value
       // stays with the route's own validator rather than the sandbox message.
       const chainId = (() => {
@@ -156,6 +165,18 @@ export function data(options: data.Options = {}) {
   return Metadata.attach(app, openapi)
 }
 
+function resolveChainSelector(options: {
+  basePath: string
+  path: string
+  query: string | undefined
+}) {
+  const rpc = Path.join(options.basePath, 'rpc')
+  if (options.path === rpc) return undefined
+  if (options.path.startsWith(`${rpc}/`))
+    return options.path.slice(rpc.length + 1).split('/')[0] || undefined
+  return options.query
+}
+
 export declare namespace data {
   /** Options for the data route group. */
   type Options = {

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

@@ -93,6 +93,160 @@ describe('FundingRouteProviders', () => {
     })
   })
 
+  test('builds an authenticated exact-input Across quote request', async () => {
+    const route = await staticRoute('across')
+    const request = FundingRouteProviders.createAcrossQuoteRequest({
+      apiKey: 'across-api-key',
+      baseUrl: 'https://across.test/api/',
+      depositor: '0x1111111111111111111111111111111111111111',
+      integratorId: '0xdead',
+      recipient: '0x2222222222222222222222222222222222222222',
+      route,
+    })
+
+    expect(request.url.pathname).toBe('/api/swap/approval')
+    expect(request.url.searchParams.get('originChainId')).toBe('8453')
+    expect(request.url.searchParams.get('destinationChainId')).toBe('4217')
+    expect(request.url.searchParams.get('amount')).toBe('1000000')
+    expect(request.url.searchParams.get('integratorId')).toBe('0xdead')
+    expect(request.url.searchParams.get('tradeType')).toBe('exactInput')
+    expect(request.url.searchParams.get('skipOriginTxEstimation')).toBe('true')
+    expect(request.url.searchParams.get('strictTradeType')).toBe('true')
+    expect(request.url.searchParams.get('depositor')).toBe(
+      '0x1111111111111111111111111111111111111111',
+    )
+    expect(request.url.searchParams.get('recipient')).toBe(
+      '0x2222222222222222222222222222222222222222',
+    )
+    expect(new Headers(request.headers).get('authorization')).toBe('Bearer across-api-key')
+  })
+
+  test('calls the runtime fetch method with its global receiver', async () => {
+    const route = await staticRoute('across')
+    vi.useFakeTimers()
+    vi.setSystemTime(now())
+    const fetch = vi.fn(function (this: unknown) {
+      expect(this).toBe(globalThis)
+      return Promise.resolve(jsonResponse(acrossQuoteResponse(route)))
+    })
+    vi.stubGlobal('fetch', fetch)
+
+    try {
+      const quote = FundingRouteProviders.acrossQuote({
+        apiKey: 'across-api-key',
+        integratorId: '0xdead',
+      })
+      const result = await quote(
+        { depositor: '0x1111111111111111111111111111111111111111', route },
+        new AbortController().signal,
+      )
+
+      expect(result.outputAmount).toBe('990000')
+      expect(fetch).toHaveBeenCalledOnce()
+    } finally {
+      vi.unstubAllGlobals()
+      vi.useRealTimers()
+    }
+  })
+
+  test('normalizes an Across quote payload', async () => {
+    const route = await staticRoute('across')
+    const result = FundingRouteProviders.parseAcrossQuote({
+      body: acrossQuoteResponse(route),
+      now: now(),
+      route,
+    })
+
+    expect(result).toMatchObject({
+      estimatedSeconds: 2,
+      expiresAt: '2026-01-01T00:01:00.000Z',
+      fees: {
+        total: {
+          amount: '1200',
+          amountUsd: '0.0012',
+          bps: 12,
+          token: { chainId: 'eip155:8453', symbol: 'USDC' },
+        },
+        totalMax: {
+          amount: '1800',
+          amountUsd: '0.0018',
+          bps: 18,
+          token: { chainId: 'eip155:8453', symbol: 'USDC' },
+        },
+      },
+      minimumOutputAmount: '988000',
+      outputAmount: '990000',
+      sampledAt: '2026-01-01T00:00:00.000Z',
+    })
+  })
+
+  test('maps Across HTTP errors into stable provider errors', () => {
+    expect(
+      FundingRouteProviders.mapAcrossQuoteError({ body: { code: 'RATE_LIMITED' }, status: 429 }),
+    ).toBeInstanceOf(FundingRoutes.ProviderRateLimitError)
+    expect(
+      FundingRouteProviders.mapAcrossQuoteError({ body: { code: 'NO_ROUTE' }, status: 400 }),
+    ).toBeInstanceOf(FundingRoutes.ProviderQuoteUnavailableError)
+    const error = FundingRouteProviders.mapAcrossQuoteError({
+      body: { code: 'NOT_FOUND' },
+      status: 404,
+    })
+    expect(error).toMatchObject({ name: 'FundingRouteProviders.ProviderResponseError' })
+    expect(FundingRouteProviders.acrossQuoteFailure({ cause: error })).toEqual({
+      code: 'NOT_FOUND',
+      failure: 'http',
+      id: 'across',
+      operation: 'swap/approval',
+      status: 404,
+    })
+  })
+
+  test('rejects invalid Across configuration during adapter construction', () => {
+    expect(() =>
+      FundingRouteProviders.acrossQuote({ apiKey: 'across-api-key', integratorId: 'tempo' }),
+    ).toThrowErrorMatchingInlineSnapshot(`[FundingRouteProviders.ProviderConfigurationError]`)
+  })
+
+  test('rejects malformed Across quote payloads', async () => {
+    const route = await staticRoute('across')
+    const failure = (() => {
+      try {
+        FundingRouteProviders.parseAcrossQuote({
+          body: { expectedOutputAmount: '990000' },
+          now: now(),
+          route,
+        })
+        throw new Error('Expected malformed payload to fail')
+      } catch (cause) {
+        return cause
+      }
+    })()
+    expect(failure).toMatchObject({ name: 'FundingRouteProviders.ProviderPayloadError' })
+    expect(FundingRouteProviders.acrossQuoteFailure({ cause: failure })).toEqual({
+      failure: 'payload',
+      id: 'across',
+      operation: 'swap/approval',
+    })
+  })
+
+  test('rejects inconsistent Across fee summaries', async () => {
+    const route = await staticRoute('across')
+    const body = acrossQuoteResponse(route)
+    body.fees.totalMax.amount = '1000'
+    expect(() => FundingRouteProviders.parseAcrossQuote({ body, now: now(), route })).toThrow(
+      expect.objectContaining({ name: 'FundingRouteProviders.ProviderPayloadError' }),
+    )
+  })
+
+  test('rejects mismatched Across fee tokens', async () => {
+    const route = await staticRoute('across')
+    const body = acrossQuoteResponse(route)
+    body.fees.total.token.address = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
+    expect(() => FundingRouteProviders.parseAcrossQuote({ body, now: now(), route })).toThrow(
+      expect.objectContaining({ name: 'FundingRouteProviders.ProviderPayloadError' }),
+    )
+  })
+
   test('maps Relay liquidity and quote responses into quote probes', async () => {
     const requests: RecordedRequest[] = []
     const route = await staticRoute('relay')
@@ -252,6 +406,56 @@ function probeInputFromRoute(
   }
 }
 
+function acrossQuoteResponse(route: FundingRoutes.QuoteProbeInput['route']) {
+  return {
+    amountType: 'exactInput',
+    approvalTxns: [{ data: '0x1234', to: '0x2222222222222222222222222222222222222222' }],
+    checks: { balance: { actual: '1000000', expected: '1000000' } },
+    expectedFillTime: 2,
+    expectedOutputAmount: '990000',
+    fees: {
+      total: {
+        amount: '1200',
+        amountUsd: '0.0012',
+        pct: '1200000000000000',
+        token: {
+          address: route.sourceToken.address,
+          chainId: 8453,
+          decimals: 6,
+          symbol: 'USDC',
+        },
+      },
+      totalMax: {
+        amount: '1800',
+        amountUsd: '0.0018',
+        pct: '1800000000000000',
+        token: {
+          address: route.sourceToken.address,
+          chainId: 8453,
+          decimals: 6,
+          symbol: 'USDC',
+        },
+      },
+    },
+    inputAmount: '1000000',
+    inputToken: {
+      address: route.sourceToken.address,
+      chainId: 8453,
+      decimals: 6,
+      symbol: 'USDC',
+    },
+    minOutputAmount: '988000',
+    outputToken: {
+      address: route.destinationToken.address,
+      chainId: 4217,
+      decimals: 6,
+      symbol: 'USDC.e',
+    },
+    quoteExpiryTimestamp: 1767225660,
+    swapTx: { data: '0xabcd', to: '0x3333333333333333333333333333333333333333' },
+  }
+}
+
 function recordingFetch(
   requests: RecordedRequest[],
   respond: (request: RecordedRequest) => Response | Promise<Response>,