tapimo 0.10.2 → 0.12.0

package/src/internal/OpenApi.ts

@@ -1,6 +1,13 @@
 import type { Context, Env, MiddlewareHandler, ValidationTargets } from 'hono'
 import type { HasRequiredKeys } from 'hono/utils/types'
-import { resolver, type ResponsesWithResolver, validator } from 'hono-openapi'
+import {
+  describeRoute as core_describeRoute,
+  type DescribeRouteOptions,
+  resolver,
+  type ResponsesWithResolver,
+  uniqueSymbol,
+  validator,
+} from 'hono-openapi'
 import * as z from 'zod/mini'
 import * as Response from './Response.js'
 import * as Schema from './Schema.js'
@@ -41,7 +48,6 @@ const schemaOptions = { options: { override: recoverExamples, unrepresentable: '
 // re-exports because `uniqueSymbol` is a `unique symbol` whose identity is
 // lost when copied through a `const` declaration.
 export {
-  describeRoute,
   type HandlerUniqueProperty,
   resolver,
   type ResponsesWithResolver,
@@ -49,12 +55,53 @@ export {
   validator,
 } from 'hono-openapi'
 
+function cloneResponseContainers(spec: DescribeRouteOptions): DescribeRouteOptions {
+  if (!spec.responses) return spec
+  return {
+    ...spec,
+    responses: Object.fromEntries(
+      Object.entries(spec.responses).map(([status, response]) => [
+        status,
+        !response || !('content' in response)
+          ? response
+          : {
+              ...response,
+              content: Object.fromEntries(
+                Object.entries(response.content ?? {}).map(([mediaType, media]) => [
+                  mediaType,
+                  { ...media },
+                ]),
+              ),
+            },
+      ]),
+    ),
+  }
+}
+
+/** Describes a route without allowing spec generation to mutate reusable response definitions. */
+export function describeRoute(spec: DescribeRouteOptions): MiddlewareHandler {
+  const handler = core_describeRoute(spec)
+  Object.defineProperty(handler, uniqueSymbol, {
+    get: () => ({ spec: cloneResponseContainers(spec) }),
+  })
+  return handler
+}
+
+/** Emits a named OpenAPI component and uses its `$ref` wherever the schema appears. */
+export function component<const schema extends z.ZodMiniType>(
+  schema: schema,
+  name: string,
+): schema {
+  const cloned = schema.clone()
+  z.globalRegistry.add(cloned, { ...z.globalRegistry.get(schema), ref: name })
+  return cloned as schema
+}
+
 /**
  * Standard machine-readable `error.code` values per status, shared API-wide.
  * The reference enumerates `error.code` to these so generated clients narrow it
- * to a literal union instead of an open `string`. 400 and 404 vary per
- * operation; the values here are the API-wide supersets, narrowable per route
- * via the `codes` override in {@link responses.Options}.
+ * to a literal union instead of an open `string`. The values here are shared
+ * defaults; operation-specific codes are supplied through {@link responses.Options}.
  */
 export const errorCodes = {
   400: [
@@ -80,7 +127,7 @@ export const errorCodes = {
     'api_key_malformed',
   ],
   401: ['api_key_missing', 'api_key_invalid', 'unauthorized'],
-  403: ['api_key_forbidden', 'api_key_ip_forbidden', 'limit_exceeded'],
+  403: ['api_key_forbidden', 'api_key_ip_forbidden', 'forbidden'],
   404: [
     'not_found',
     'token_not_found',
@@ -164,11 +211,78 @@ export const rateLimitHeaders = {
 /** Representative `requestId` used in error-body examples. */
 const exampleRequestId = '0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9'
 
-/** Builds the `application/json` content for a standard error response: the enumerated-code envelope plus an example body. */
-function errorContent(codes: readonly [string, ...string[]] | undefined, message: string) {
+const standardErrorNames = {
+  400: 'InvalidRequestError',
+  401: 'AuthenticationError',
+  403: 'ForbiddenError',
+  404: 'ResourceNotFoundError',
+  429: 'RateLimitError',
+  500: 'InternalError',
+  501: 'NotImplementedError',
+  502: 'UpstreamError',
+} as const satisfies Record<keyof typeof errorCodes, string>
+
+const reservedErrorNames = new Set<string>(Object.values(standardErrorNames))
+const errorSchemas = new Map<string, z.ZodMiniType>()
+
+function errorName(status: number, codes: readonly string[]) {
+  const standard = errorCodes[status as keyof typeof errorCodes]
+  if (
+    standard &&
+    standard.length === codes.length &&
+    [...standard].sort().every((code, index) => code === codes[index])
+  )
+    return standardErrorNames[status as keyof typeof standardErrorNames]
+  const name = `${codes
+    .map((code) =>
+      code
+        .split('_')
+        .map((part) => `${part[0]?.toUpperCase()}${part.slice(1)}`)
+        .join(''),
+    )
+    .join('Or')}Error`
+  if (reservedErrorNames.has(name)) return `${name.slice(0, -'Error'.length)}${status}Error`
+  return name
+}
+
+function errorSchema(status: number, codes: readonly [string, ...string[]] | undefined) {
+  const defaults = errorCodes[status as keyof typeof errorCodes]
+  if (!codes && !defaults) {
+    const cached = errorSchemas.get('*')
+    if (cached) return cached
+    const schema = component(Schema.errorResponse(), 'ErrorResponse')
+    errorSchemas.set('*', schema)
+    return schema
+  }
+  const normalized = [...(codes ?? defaults ?? [])].sort() as [string, ...string[]]
+  const key = normalized.join('\0')
+  const cached = errorSchemas.get(key)
+  if (cached) return cached
+  const schema = component(Schema.errorResponse(normalized), errorName(status, normalized))
+  errorSchemas.set(key, schema)
+  return schema
+}
+
+function mergeErrorCodes(
+  status: number,
+  codes: readonly string[] | undefined,
+): readonly [string, ...string[]] | undefined {
+  if (!codes) return errorCodes[status as keyof typeof errorCodes]
+  if (status !== 400 && status !== 403)
+    return codes.length ? (codes as [string, ...string[]]) : undefined
+  const baseline = status === 400 ? (['api_key_malformed'] as const) : errorCodes[403]
+  return [...new Set([...baseline, ...codes])] as [string, ...string[]]
+}
+
+/** Builds the `application/json` content for a standard error response: the named enumerated-code envelope plus an example body. */
+function errorContent(
+  status: number,
+  codes: readonly [string, ...string[]] | undefined,
+  message: string,
+) {
   return {
     'application/json': {
-      schema: resolver(Schema.errorResponse(codes), schemaOptions),
+      schema: resolver(errorSchema(status, codes), schemaOptions),
       example: { error: { code: codes?.[0] ?? 'error', message }, requestId: exampleRequestId },
     },
   }
@@ -186,32 +300,30 @@ export const paymentChallenge = {
   headers: { 'WWW-Authenticate': headerRef('WwwAuthenticate') },
 } as const
 
-/** Shared `429` rate-limit response, registered as `components.responses.RateLimited`. */
-const rateLimitedResponse = {
-  content: errorContent(errorCodes[429], 'Rate limit exceeded.'),
-  description:
-    'Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead.',
-  headers: { ...rateLimitHeaders },
-}
-
-/** Shared `500` internal-error response, registered as `components.responses.InternalError`. */
-const serverErrorResponse = {
-  content: errorContent(errorCodes[500], 'Internal server error.'),
-  description: 'Internal server error.',
-}
+type ResponseComponentName = 'InternalError' | 'PaymentRequired' | 'RateLimited'
 
 /**
  * Reusable responses registered under `components.responses` (see `App.create`)
  * and `$ref`-erenced from operations, so the uniform `402`/`429`/`500` responses
  * are defined once instead of inlined on every operation.
  */
-export const responseComponents: ResponsesWithResolver = {
-  InternalError: serverErrorResponse,
-  PaymentRequired: paymentChallenge,
-  RateLimited: rateLimitedResponse,
+export function responseComponents(): ResponsesWithResolver {
+  return {
+    InternalError: {
+      content: errorContent(500, errorCodes[500], 'Internal server error.'),
+      description: 'Internal server error.',
+    },
+    PaymentRequired: paymentChallenge,
+    RateLimited: {
+      content: errorContent(429, errorCodes[429], 'Rate limit exceeded.'),
+      description:
+        'Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead.',
+      headers: { ...rateLimitHeaders },
+    },
+  }
 }
 
-const responseRef = (name: keyof typeof responseComponents) => ({
+const responseRef = (name: ResponseComponentName) => ({
   $ref: `#/components/responses/${name}`,
 })
 
@@ -232,22 +344,22 @@ export function standardError(
 ): ResponsesWithResolver[string] {
   if (status === 429) return responseRef('RateLimited')
   if (status === 500) return responseRef('InternalError')
-  return { content: errorContent(codes ?? errorCodes[status], description), description }
+  return { content: errorContent(status, mergeErrorCodes(status, codes), description), description }
 }
 
 /**
  * Builds an OpenAPI `responses` map with the API's standard error responses
  * pre-filled, plus the success response (with rate-limit headers):
  *
- * - `400` invalid request, `401` missing/invalid key, `429` rate limited,
- *   `500` internal error, and `502` upstream failure on every operation;
- * - `403`/`404`/`409`/`412`/`413`/`415` only when an `errors` entry is set.
+ * - `400` invalid request, `401` missing/invalid key, `403` forbidden, `429`
+ *   rate limited, `500` internal error, and `502` upstream failure on every operation;
+ * - `404`/`409`/`412`/`413`/`415` only when an `errors` entry is set.
  *
- * `error.code` is enumerated per status from {@link errorCodes}; narrow 400/404
- * to a route's exact codes by passing `{ description, codes }` for that status.
- * `429`/`500` `$ref` the shared {@link responseComponents}. `402` is not emitted
- * here — it is injected per operation from the route's MPP policy during spec
- * generation (see `App.ts`).
+ * `error.code` is enumerated per status from {@link errorCodes}. Operation-level
+ * 400/403 codes merge with shared auth codes; other overrides replace defaults.
+ * The default `429` and `500` `$ref` shared {@link responseComponents}; an exact
+ * operation-level `429` override is emitted inline with the standard headers.
+ * `402` is injected per operation from the route's MPP policy in `App.ts`.
  */
 export function responses<schema extends z.ZodMiniType>(
   options: responses.Options<schema>,
@@ -257,10 +369,11 @@ export function responses<schema extends z.ZodMiniType>(
     const override = errors?.[status as 400]
     const description =
       typeof override === 'string' ? override : (override?.description ?? fallback)
-    const codes =
-      (typeof override === 'object' ? override.codes : undefined) ??
-      errorCodes[status as keyof typeof errorCodes]
-    return { content: errorContent(codes, description), description }
+    const codes = mergeErrorCodes(status, typeof override === 'object' ? override.codes : undefined)
+    return {
+      content: errorContent(status, codes, description),
+      description,
+    }
   }
   return {
     200: {
@@ -279,13 +392,15 @@ export function responses<schema extends z.ZodMiniType>(
     },
     400: error(400, 'Invalid request.'),
     401: error(401, 'Missing or invalid API key.'),
-    ...(errors?.[403] && { 403: error(403, 'Forbidden.') }),
+    403: error(403, 'Forbidden.'),
     ...(errors?.[404] && { 404: error(404, 'Not found.') }),
     ...(errors?.[409] && { 409: error(409, 'Conflict.') }),
     ...(errors?.[412] && { 412: error(412, 'Precondition failed.') }),
     ...(errors?.[413] && { 413: error(413, 'Payload too large.') }),
     ...(errors?.[415] && { 415: error(415, 'Unsupported media type.') }),
-    429: responseRef('RateLimited'),
+    429: errors?.[429]
+      ? { ...error(429, 'Rate limit exceeded.'), headers: { ...rateLimitHeaders } }
+      : responseRef('RateLimited'),
     500: responseRef('InternalError'),
     ...(errors?.[501] && { 501: error(501, 'Not implemented.') }),
     502: error(502, 'Upstream data failure.'),
@@ -295,23 +410,22 @@ export function responses<schema extends z.ZodMiniType>(
 export declare namespace responses {
   /**
    * Override for a standard error response: a description string, or an object
-   * adding the exact `codes` that status can return (narrowing the enum).
+   * adding operation codes. Codes replace defaults except shared 400/403 auth codes.
    */
   type ErrorOverride =
     | string
     | {
         /** Human-readable description of the error response. */
         description?: string | undefined
-        /** Exact `error.code` values this status returns for the operation. */
-        codes?: readonly [string, ...string[]] | undefined
+        /** Operation-specific `error.code` values for this status. */
+        codes?: readonly string[] | undefined
       }
 
   /** Options for building a standard OpenAPI responses map. */
   type Options<schema> = {
     /**
-     * Optional overrides for standard error responses (description and/or exact
-     * `error.code` enum). Setting `403`/`404`/`409`/`412`/`413`/`415` also
-     * includes that status in the map.
+     * Optional overrides for standard error responses. Setting
+     * `404`/`409`/`412`/`413`/`415` includes that status in the map.
      */
     errors?:
       | {
@@ -319,7 +433,7 @@ export declare namespace responses {
           400?: ErrorOverride | undefined
           /** Override for the 401 response. */
           401?: ErrorOverride | undefined
-          /** Override for the 403 response. Setting this includes 403 in the map. */
+          /** Add operation-specific 403 codes or override its description. */
           403?: ErrorOverride | undefined
           /** Override for the 404 response. Setting this includes 404 in the map. */
           404?: ErrorOverride | undefined
@@ -331,6 +445,8 @@ export declare namespace responses {
           413?: ErrorOverride | undefined
           /** Override for the 415 response. Setting this includes 415 in the map. */
           415?: ErrorOverride | undefined
+          /** Override the shared 429 response with operation-specific rate-limit codes. */
+          429?: ErrorOverride | undefined
           /** Override for the 501 response. Setting this includes 501 in the map. */
           501?: ErrorOverride | undefined
           /** Override for the 502 response. */

package/src/internal/Response.test.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono'
+import { Tidx } from 'tidx.ts'
 
 import * as Response from './Response.js'
 
@@ -25,4 +26,98 @@ describe('upstream', () => {
     `)
     expect(captured).toBe(cause)
   })
+
+  test('returns a query error when a positional page times out', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Request timeout',
+      new globalThis.Response(null, { status: 408 }),
+    )
+    let captured: Error | undefined
+
+    app.use(async (c, next) => {
+      await next()
+      captured = c.error
+    })
+    app.get('/', (c) => Response.upstream(c, cause, { page: 2 }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "query_invalid",
+          "message": "The requested page timed out. Use cursor pagination for deep traversal.",
+        },
+      }
+    `)
+    expect(captured).toBe(cause)
+  })
+
+  test('returns a query error when a positional page is rejected', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Query rejected',
+      new globalThis.Response(null, { status: 422 }),
+    )
+    let captured: Error | undefined
+
+    app.use(async (c, next) => {
+      await next()
+      captured = c.error
+    })
+    app.get('/', (c) => Response.upstream(c, cause, { page: 584 }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "query_invalid",
+          "message": "The requested page was rejected. Use cursor pagination for deep traversal.",
+        },
+      }
+    `)
+    expect(captured).toBe(cause)
+  })
+
+  test('keeps timeouts without a deep positional page as upstream errors', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Request timeout',
+      new globalThis.Response(null, { status: 408 }),
+    )
+    app.get('/', (c) => Response.upstream(c, cause, { page: undefined }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`502`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "upstream_error",
+          "message": "Upstream service could not complete the request",
+        },
+      }
+    `)
+  })
+
+  test('keeps query rejections without a deep positional page as upstream errors', async () => {
+    const app = new Hono()
+    const cause = new Tidx.FetchRequestError(
+      'Query rejected',
+      new globalThis.Response(null, { status: 422 }),
+    )
+    app.get('/', (c) => Response.upstream(c, cause, { page: undefined }))
+
+    const response = await app.request('/')
+    expect(response.status).toMatchInlineSnapshot(`502`)
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "upstream_error",
+          "message": "Upstream service could not complete the request",
+        },
+      }
+    `)
+  })
 })

package/src/internal/Response.ts

@@ -1,6 +1,8 @@
 import type { Context } from 'hono'
 import type * as z from 'zod/mini'
 
+import * as Tidx from './Tidx.js'
+
 /** Creates a JSON error response. */
 export function error<const status extends error.Status, const code extends string>(
   c: Context,
@@ -39,14 +41,34 @@ export function unsupportedChainId(c: Context, chainId: number, supported: Itera
 }
 
 /**
- * Maps an unexpected upstream failure to a stable 502 JSON error envelope.
+ * Maps upstream failures to 502, except TIDX query failures after the first positional page return 400.
  * Preserves `Error` causes for reporting and rethrows non-`Error` causes.
  */
-export function upstream(c: Context, cause: unknown) {
+export function upstream(c: Context, cause: unknown): upstream.Response
+export function upstream(
+  c: Context,
+  cause: unknown,
+  options: upstream.Options,
+): upstream.PageResponse
+export function upstream(c: Context, cause: unknown, options?: upstream.Options) {
   if (cause instanceof Error) {
     // Preserve the original error for error-reporting middleware without
     // exposing provider URLs, payloads, or credentials in the response.
     c.error = cause
+    if (options?.page !== undefined && options.page > 1) {
+      if (Tidx.isQueryTimeout(cause))
+        return error(c, {
+          code: 'query_invalid',
+          message: 'The requested page timed out. Use cursor pagination for deep traversal.',
+          status: 400,
+        })
+      if (Tidx.isQueryRejection(cause))
+        return error(c, {
+          code: 'query_invalid',
+          message: 'The requested page was rejected. Use cursor pagination for deep traversal.',
+          status: 400,
+        })
+    }
     return error(c, {
       code: 'upstream_error',
       message: 'Upstream service could not complete the request',
@@ -56,6 +78,22 @@ export function upstream(c: Context, cause: unknown) {
   throw cause
 }
 
+export declare namespace upstream {
+  /** Pagination context for classifying a deep-page query failure. */
+  type Options = {
+    /** Validated positional page number, when requested. */
+    page: number | undefined
+  }
+
+  /** Upstream response for routes that support positional pagination. */
+  type PageResponse =
+    | ReturnType<typeof error<400, 'query_invalid'>>
+    | ReturnType<typeof error<502, 'upstream_error'>>
+
+  /** Default upstream error response. */
+  type Response = ReturnType<typeof error<502, 'upstream_error'>>
+}
+
 /**
  * Validates `value` against `schema`. Returns the parsed value on success or
  * throws a generic upstream error so the public response body never leaks Zod

package/src/internal/Schema.test.ts

@@ -1,3 +1,5 @@
+import * as z from 'zod/mini'
+
 import * as Schema from './Schema.js'
 
 describe('ChainId', () => {
@@ -33,6 +35,38 @@ describe('ChainIdQuery', () => {
   })
 })
 
+describe('Limit', () => {
+  test('defaults to 10 and accepts page sizes through 50', () => {
+    expect(Schema.Limit.parse(undefined)).toMatchInlineSnapshot(`10`)
+    expect(Schema.Limit.parse('5')).toMatchInlineSnapshot(`5`)
+    expect(Schema.Limit.parse('50')).toMatchInlineSnapshot(`50`)
+  })
+
+  test('caps larger page sizes at 50', () => {
+    expect(Schema.Limit.parse('51')).toMatchInlineSnapshot(`50`)
+    expect(Schema.Limit.parse('200')).toMatchInlineSnapshot(`50`)
+    expect(Schema.Limit.parse('10000')).toMatchInlineSnapshot(`50`)
+  })
+
+  test('rejects page sizes below the minimum', () => {
+    expect(Schema.Limit.safeParse('4').success).toMatchInlineSnapshot(`false`)
+  })
+})
+
+describe('pageChecks', () => {
+  const Query = z
+    .object({ cursor: Schema.Cursor, limit: Schema.Limit, page: Schema.Page })
+    .check(...Schema.pageChecks())
+
+  test('accepts positional pages through the 500-row window', () => {
+    expect(Query.safeParse({ limit: '10', page: '50' }).success).toMatchInlineSnapshot(`true`)
+  })
+
+  test('rejects deeper positional pages', () => {
+    expect(Query.safeParse({ limit: '10', page: '51' }).success).toMatchInlineSnapshot(`false`)
+  })
+})
+
 describe('timestampBound', () => {
   test('normalizes RFC 3339 offsets to UTC', () => {
     const bound = Schema.timestampBound('swaps', 'from')

package/src/internal/Schema.ts

@@ -191,6 +191,8 @@ export const ErrorDetail = z
   })
   .check(z.describe('A single problem with the request.'))
 
+z.globalRegistry.add(ErrorDetail, { ...z.globalRegistry.get(ErrorDetail), ref: 'ErrorDetail' })
+
 /**
  * Builds the global error envelope, optionally enumerating `error.code` to a
  * fixed set of machine-readable codes. Pass the codes a given status can return
@@ -337,11 +339,22 @@ export const TokenAmount = describe(
  */
 export const minLimit = 5
 
+/** Maximum number of rows returned per page. Larger requests are clamped to this value. */
+export const maxLimit = 50
+
 /** Page-size query parameter shared across list endpoints. */
 export const Limit = z
-  ._default(z.coerce.number().check(z.int(), z.gte(minLimit), z.lte(200)), 10)
+  ._default(
+    z.pipe(
+      z.coerce.number().check(z.int(), z.gte(minLimit)),
+      z.transform((value) => Math.min(value, maxLimit)),
+    ),
+    10,
+  )
   .check(
-    z.describe('How many items to return per page (5\u2013200, default 10).'),
+    z.describe(
+      'How many items to return per page (5\u201350, default 10). Use `nextCursor` to fetch more.',
+    ),
     z.meta({ examples: [10] }),
   )
 
@@ -373,12 +386,10 @@ export const Cursor = z
 
 /**
  * Maximum page window (`page × limit` rows) accepted by positional pagination.
- * Mirrors the indexer's own 10k row ceiling, and the bounded-window convention
- * of comparable APIs (Elasticsearch `max_result_window`, Zendesk's 100-page
- * cap): shallow page-numbered access is served positionally, deep traversal
- * must use cursors.
+ * Stays below the indexer's own 10k row ceiling so large offsets do not reach
+ * the indexer. Deeper traversal must use cursors.
  */
-export const maxPageWindow = 10_000
+export const maxPageWindow = 500
 
 /**
  * Page-number query parameter (1-indexed) shared by list endpoints that
@@ -432,8 +443,8 @@ export const NextCursor = z
  * count is computed by a capped subquery (`… LIMIT countCap`) so it can't blow
  * the indexer's execution budget on the 10⁹-plus row tables; when the bound is
  * hit the count is a lower bound, signalled by `Meta.totalCountCapped`. Mirrors the
- * indexer's own 10k row ceiling (see {@link maxPageWindow}) and the capped-count
- * conventions of comparable APIs (Stripe Search's 10k `total_count`,
+ * indexer's own 10k row ceiling and the capped-count conventions of comparable
+ * APIs (Stripe Search's 10k `total_count`,
  * Elasticsearch `track_total_hits`, Shopify's `Count.precision`).
  */
 export const countCap = 10_000