tapimo 0.0.0 → 0.0.2

package/src/internal/OpenApi.logo.ts

@@ -0,0 +1,18 @@
+// Tempo API wordmark logos for the docs header, theme-aware. `dark` (white
+// text) renders in dark mode, `light` (black text) in light mode. Inlined as
+// SVG data URIs so the standalone reference needs no external asset hosting.
+//
+// THIS FILE IS GENERATED (extracted from the Website 2.0 assets).
+const dark = `<svg width="626" height="181" viewBox="0 0 626 181" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M45.4158 136H18.9697L43.4807 61.1767H12.1324L18.9697 39.2458H106.306L99.4692 61.1767H69.7979L45.4158 136ZM143.83 136H81.1333L112.611 39.2458H175.049L169.115 57.6936H132.865L126.285 78.4635H161.375L155.44 96.6533H120.222L113.643 117.552H149.635L143.83 136ZM172.207 136H151.179L182.786 39.2458H217.875L216.714 91.4931L250.901 39.2458H289.344L257.867 136H231.55L252.449 70.9812H252.062L209.103 136H193.493L194.138 70.2071H193.88L172.207 136ZM318.946 57.1776L308.755 88.3969H311.593C318.043 88.3969 323.418 86.8919 327.718 83.8817C332.019 80.7856 334.814 76.3994 336.104 70.7231C337.222 65.8209 336.62 62.3378 334.298 60.2737C331.976 58.2096 328.105 57.1776 322.687 57.1776H318.946ZM293.403 136H266.957L298.434 39.2458H330.557C337.953 39.2458 344.317 40.4498 349.649 42.8579C355.068 45.18 359.024 48.5342 361.518 52.9204C364.098 57.2206 364.958 62.2518 364.098 68.014C362.98 75.5824 360.056 82.2477 355.326 88.0099C350.595 93.7722 344.446 98.2444 336.878 101.426C329.396 104.523 321.01 106.071 311.722 106.071H303.078L293.403 136ZM427.133 129.808C418.361 134.968 409.03 137.548 399.139 137.548H398.881C390.109 137.548 382.712 135.613 376.692 131.743C370.758 127.787 366.501 122.454 363.921 115.746C361.427 109.038 360.825 101.685 362.115 93.6862C363.749 83.6237 367.49 74.3353 373.338 65.8209C379.186 57.3066 386.497 50.5123 395.269 45.438C404.041 40.3638 413.416 37.8267 423.392 37.8267H423.65C432.767 37.8267 440.292 39.7618 446.226 43.632C452.247 47.5021 456.418 52.7914 458.74 59.4997C461.148 66.1219 461.664 73.5613 460.288 81.8176C458.654 91.5361 454.913 100.695 449.064 109.296C443.216 117.81 435.906 124.648 427.133 129.808ZM390.625 113.166C392.947 117.552 396.989 119.745 402.751 119.745H403.009C407.74 119.745 412.126 117.982 416.168 114.456C420.296 110.844 423.779 106.028 426.617 100.007C429.542 93.9872 431.692 87.2789 433.068 79.8825C434.358 72.6582 433.842 66.853 431.52 62.4668C429.198 57.9946 425.198 55.7585 419.522 55.7585H419.264C414.878 55.7585 410.621 57.5646 406.493 61.1767C402.45 64.7889 398.924 69.6481 395.914 75.7544C392.904 81.8606 390.711 88.4829 389.335 95.6212C387.959 102.846 388.389 108.694 390.625 113.166Z" fill="white"/>
+<rect x="498" y="51" width="128" height="78" fill="#2B2B2B"/>
+<path d="M509.595 111L522.555 68.4H529.515L542.475 111H536.955L526.035 73.08L515.115 111H509.595ZM516.135 98.88L517.935 93.84H534.135L535.935 98.88H516.135ZM549.412 111V68.4H562.372C565.332 68.4 567.912 68.92 570.112 69.96C572.312 71 574.012 72.5 575.212 74.46C576.412 76.38 577.012 78.7 577.012 81.42C577.012 84.14 576.412 86.48 575.212 88.44C574.012 90.36 572.312 91.84 570.112 92.88C567.912 93.92 565.332 94.44 562.372 94.44H554.572V111H549.412ZM554.572 89.4H561.772C565.132 89.4 567.612 88.72 569.212 87.36C570.812 85.96 571.612 83.98 571.612 81.42C571.612 78.82 570.812 76.84 569.212 75.48C567.612 74.12 565.132 73.44 561.772 73.44H554.572V89.4ZM584.788 111V105.96H595.408V73.44H584.788V68.4H611.188V73.44H600.568V105.96H611.188V111H584.788Z" fill="#B2B2B2"/>
+</svg>`
+const light = `<svg width="626" height="181" viewBox="0 0 626 181" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M45.4158 136H18.9697L43.4807 61.1767H12.1324L18.9697 39.2458H106.306L99.4692 61.1767H69.7979L45.4158 136ZM143.83 136H81.1333L112.611 39.2458H175.049L169.115 57.6936H132.865L126.285 78.4635H161.375L155.44 96.6533H120.222L113.643 117.552H149.635L143.83 136ZM172.207 136H151.179L182.786 39.2458H217.875L216.714 91.4931L250.901 39.2458H289.344L257.867 136H231.55L252.449 70.9812H252.062L209.103 136H193.493L194.138 70.2071H193.88L172.207 136ZM318.946 57.1776L308.755 88.3969H311.593C318.043 88.3969 323.418 86.8919 327.718 83.8817C332.019 80.7856 334.814 76.3994 336.104 70.7231C337.222 65.8209 336.62 62.3378 334.298 60.2737C331.976 58.2096 328.105 57.1776 322.687 57.1776H318.946ZM293.403 136H266.957L298.434 39.2458H330.557C337.953 39.2458 344.317 40.4498 349.649 42.8579C355.068 45.18 359.024 48.5342 361.518 52.9204C364.098 57.2206 364.958 62.2518 364.098 68.014C362.98 75.5824 360.056 82.2477 355.326 88.0099C350.595 93.7722 344.446 98.2444 336.878 101.426C329.396 104.523 321.01 106.071 311.722 106.071H303.078L293.403 136ZM427.133 129.808C418.361 134.968 409.03 137.548 399.139 137.548H398.881C390.109 137.548 382.712 135.613 376.692 131.743C370.758 127.787 366.501 122.454 363.921 115.746C361.427 109.038 360.825 101.685 362.115 93.6862C363.749 83.6237 367.49 74.3353 373.338 65.8209C379.186 57.3066 386.497 50.5123 395.269 45.438C404.041 40.3638 413.416 37.8267 423.392 37.8267H423.65C432.767 37.8267 440.292 39.7618 446.226 43.632C452.247 47.5021 456.418 52.7914 458.74 59.4997C461.148 66.1219 461.664 73.5613 460.288 81.8176C458.654 91.5361 454.913 100.695 449.064 109.296C443.216 117.81 435.906 124.648 427.133 129.808ZM390.625 113.166C392.947 117.552 396.989 119.745 402.751 119.745H403.009C407.74 119.745 412.126 117.982 416.168 114.456C420.296 110.844 423.779 106.028 426.617 100.007C429.542 93.9872 431.692 87.2789 433.068 79.8825C434.358 72.6582 433.842 66.853 431.52 62.4668C429.198 57.9946 425.198 55.7585 419.522 55.7585H419.264C414.878 55.7585 410.621 57.5646 406.493 61.1767C402.45 64.7889 398.924 69.6481 395.914 75.7544C392.904 81.8606 390.711 88.4829 389.335 95.6212C387.959 102.846 388.389 108.694 390.625 113.166Z" fill="black"/>
+<rect x="498" y="51" width="128" height="78" fill="#EDEDED"/>
+<path d="M509.595 111L522.555 68.4H529.515L542.475 111H536.955L526.035 73.08L515.115 111H509.595ZM516.135 98.88L517.935 93.84H534.135L535.935 98.88H516.135ZM549.412 111V68.4H562.372C565.332 68.4 567.912 68.92 570.112 69.96C572.312 71 574.012 72.5 575.212 74.46C576.412 76.38 577.012 78.7 577.012 81.42C577.012 84.14 576.412 86.48 575.212 88.44C574.012 90.36 572.312 91.84 570.112 92.88C567.912 93.92 565.332 94.44 562.372 94.44H554.572V111H549.412ZM554.572 89.4H561.772C565.132 89.4 567.612 88.72 569.212 87.36C570.812 85.96 571.612 83.98 571.612 81.42C571.612 78.82 570.812 76.84 569.212 75.48C567.612 74.12 565.132 73.44 561.772 73.44H554.572V89.4ZM584.788 111V105.96H595.408V73.44H584.788V68.4H611.188V73.44H600.568V105.96H611.188V111H584.788Z" fill="#707070"/>
+</svg>`
+const dataUri = (svg: string) => `data:image/svg+xml,${encodeURIComponent(svg)}`
+/** Theme-aware Tempo API wordmark for the docs header (`vocs.logoUrl`). */
+export const logoUrl = { dark: dataUri(dark), light: dataUri(light) }

package/src/internal/OpenApi.ts

@@ -0,0 +1,488 @@
+import type { Context, Env, MiddlewareHandler, ValidationTargets } from 'hono'
+import type { HasRequiredKeys } from 'hono/utils/types'
+import { resolver, type ResponsesWithResolver, validator } from 'hono-openapi'
+import * as z from 'zod/mini'
+import { pilatFontFaces } from './OpenApi.fonts.js'
+import * as Response from './Response.js'
+import * as Schema from './Schema.js'
+
+/**
+ * `toJSONSchema` override that re-applies `examples` zod strips from
+ * pipe/default schemas in `io: 'input'` mode. zod intentionally drops
+ * `examples` (and `default`) from the input JSON Schema of a `ZodPipe`
+ * (e.g. `chainId`, `include`, boolean queries) and a `ZodDefault`, so an
+ * `examples` attached via `z.meta(...)` on those wrappers never reaches the
+ * generated parameter. This override runs after conversion and copies the
+ * registered `examples` back onto the node's JSON Schema, so every parameter
+ * surfaces its example regardless of the underlying schema shape.
+ */
+function recoverExamples(ctx: { jsonSchema: { examples?: unknown }; zodSchema: unknown }) {
+  if (ctx.jsonSchema.examples !== undefined) return
+  const meta = z.globalRegistry.get(ctx.zodSchema as never) as { examples?: unknown } | undefined
+  if (meta?.examples === undefined) return
+  ctx.jsonSchema.examples = Array.isArray(meta.examples)
+    ? meta.examples
+    : Object.values(meta.examples as Record<string, { value: unknown }>).map((e) => e.value)
+}
+
+/**
+ * Shared zod→JSON-Schema conversion options applied to every parameter and
+ * response schema. {@link recoverExamples} re-attaches `examples` that zod
+ * strips from pipe/default schemas (e.g. `Schema.Hex`, `Schema.Quantity`), so a
+ * field's `z.meta({ examples })` survives even on a branded pipe output — no
+ * per-field non-pipe schema is needed. Supplying our own `override` opts out of
+ * hono-openapi's default zod date override, so re-add its `unrepresentable:
+ * 'any'` to keep transform/pipe nodes (which have no JSON-Schema form) emitting
+ * `{}` instead of throwing.
+ */
+const schemaOptions = { options: { override: recoverExamples, unrepresentable: 'any' } } as const
+
+// Re-export the upstream `hono-openapi` API surface used by the app so all
+// callers go through this local `OpenApi` module. Forwarded as direct named
+// 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,
+  uniqueSymbol,
+  validator,
+} from 'hono-openapi'
+
+// Theme-aware Tempo API wordmark for the docs header (`vocs.logoUrl`), inlined
+// as SVG data URIs. See {@link file://./OpenApi.logo.ts}.
+export { logoUrl } from './OpenApi.logo.js'
+
+/**
+ * Custom CSS injected into the standalone reference's shell `<head>` (via
+ * `Handler.openApi(_, { css })`), after the Vocs design-system styles so it
+ * overrides them:
+ *
+ * - Page/surface backgrounds use Tempo's near-black dark palette and pure-white
+ *   light palette via `light-dark(<light>, <dark>)`.
+ * - The dark border color is darkened (the light theme keeps its default).
+ * - Every corner is squared. The universal `!important` rule beats hard-coded
+ *   `border-radius` values and inline styles (e.g. the Scalar playground), which
+ *   overriding the radius scale variables alone would miss.
+ * - The default sans/body font is Pilat (Vocs reads `--vocs-font-family`); the
+ *   webfont is embedded via {@link pilatFontFaces}. Body stays at the default
+ *   weight (400); headings are pinned to 500, which renders Pilat Demi (the
+ *   family has no 500 cut, so Demi covers the 500-600 range — see
+ *   {@link pilatFontFaces}).
+ */
+export const css = `${pilatFontFaces}
+
+:root {
+  --vocs-font-family: "Pilat", Arial, Helvetica, sans-serif;
+  --vocs-background-color-primary: light-dark(#fafafa, #0a0a0a);
+  --vocs-background-color-surface: light-dark(#fff, #121212);
+}
+
+:is(h1, h2, h3, h4, h5, h6)[data-v] {
+  font-weight: 500;
+}
+
+/* Nudge the header logo a touch larger than the default max-h-7 (1.75rem). */
+[data-v-logo-image] {
+  max-height: 2rem;
+}
+
+/* Sidebar leaf items render Regular (the nav's 450 default otherwise resolves to
+ * Demi via the 500-600 range). Group labels ([data-v-sidebar-section-header])
+ * keep their heavier weight. */
+[data-v-sidebar-item] {
+  font-weight: 400;
+}
+
+[data-vocs-theme='dark'] {
+  --vocs-color-gray4: oklch(20% 0 0);
+  --vocs-color-gray5: oklch(0.23 0 0);
+  --vocs-border-color-primary: oklch(0.25 0 0);
+  --vocs-border-color-secondary: oklch(0.25 0 0);
+}
+
+*,
+*::before,
+*::after {
+  border-radius: 0 !important;
+}`
+
+/**
+ * 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}.
+ */
+export const errorCodes = {
+  400: [
+    'query_invalid',
+    'param_invalid',
+    'body_invalid',
+    'address_invalid',
+    'token_invalid',
+    'symbol_invalid',
+    'pair_invalid',
+    'pair_id_invalid',
+    'transaction_invalid',
+    'order_invalid',
+    'block_invalid',
+    'chain_id_invalid',
+    'chain_id_unsupported',
+    'url_invalid',
+    'api_key_malformed',
+  ],
+  401: ['api_key_missing', 'api_key_invalid', 'unauthorized'],
+  403: ['api_key_forbidden', 'limit_exceeded'],
+  404: [
+    'not_found',
+    'token_not_found',
+    'token_logo_not_found',
+    'block_not_found',
+    'transaction_not_found',
+    'receipt_not_found',
+    'order_not_found',
+    'pair_not_found',
+    'verified_token_not_found',
+    'webhook_not_found',
+    'delivery_not_found',
+    'webhooks_not_enabled',
+  ],
+  429: ['rate_limit_exceeded', 'payment_required'],
+  500: ['internal_error'],
+  502: ['upstream_error'],
+} as const satisfies Record<number, readonly [string, ...string[]]>
+
+/**
+ * Reusable response-header definitions, registered under `components.headers`
+ * (see `App.ts`) and `$ref`-erenced from 200/429 responses. The rate-limit
+ * headers reflect the quota the request consumed; they are absent on edge-cache
+ * hits (served before metering) and on `402` payment challenges (owned by mppx,
+ * which sets `WWW-Authenticate`/`Payment-Receipt` instead).
+ */
+export const headerComponents = {
+  RateLimitLimit: {
+    description: 'How many requests you may make in the current time window. Not sent on cached responses or `402` payment challenges.', // prettier-ignore
+    schema: { type: 'integer' },
+  },
+  RateLimitRemaining: {
+    description: 'How many requests you have left in the current window before you are rate-limited. Not sent on cached responses or `402` payment challenges.', // prettier-ignore
+    schema: { type: 'integer' },
+  },
+  RateLimitReset: {
+    description: 'When the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or `402` payment challenges.', // prettier-ignore
+    schema: { type: 'integer' },
+  },
+  RateLimitScope: {
+    description: 'Which quota this request counted against (e.g. `data:read`). Not sent on cached responses or `402` payment challenges.', // prettier-ignore
+    schema: { type: 'string' },
+  },
+  RetryAfter: {
+    description:
+      'How many seconds to wait before trying again. Sent with `429` (rate-limited) responses.',
+    schema: { type: 'integer' },
+  },
+  TempoRequestId: {
+    description: 'A unique id for this request, returned on every response (and as `requestId` in error bodies). Include it when contacting support so we can find your request.', // prettier-ignore
+    schema: { type: 'string' },
+  },
+  WwwAuthenticate: {
+    description: 'On a `402` response, the payment challenge to satisfy. Use it to build the `Authorization: Payment` credential and retry the request.', // prettier-ignore
+    schema: { type: 'string' },
+  },
+} as const
+
+const headerRef = (name: keyof typeof headerComponents) => ({
+  $ref: `#/components/headers/${name}`,
+})
+
+/** Response headers attached to metered success (2xx) responses. */
+export const successHeaders = {
+  'RateLimit-Limit': headerRef('RateLimitLimit'),
+  'RateLimit-Remaining': headerRef('RateLimitRemaining'),
+  'RateLimit-Reset': headerRef('RateLimitReset'),
+  'RateLimit-Scope': headerRef('RateLimitScope'),
+  'tempo-request-id': headerRef('TempoRequestId'),
+}
+
+/** Response headers attached to `429` rate-limit responses. */
+export const rateLimitHeaders = {
+  ...successHeaders,
+  'Retry-After': headerRef('RetryAfter'),
+}
+
+/** 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) {
+  return {
+    'application/json': {
+      schema: resolver(Schema.errorResponse(codes), schemaOptions),
+      example: { error: { code: codes?.[0] ?? 'error', message }, requestId: exampleRequestId },
+    },
+  }
+}
+
+/**
+ * `402` payment-challenge response, injected per operation for MPP-enabled
+ * routes during spec generation (see `App.create`). The challenge is
+ * protocol-native (owned by mppx) rather than the JSON error envelope, so it
+ * declares no JSON body — only the `WWW-Authenticate` header.
+ */
+export const paymentChallenge = {
+  description:
+    'Payment required. This endpoint accepts MPP payment, and the request either exceeded free quota or needs a paid request credential. The challenge is protocol-native (handled by mppx), not the JSON error envelope: read the `WWW-Authenticate` header and retry with `Authorization: Payment <credential>`. A successful paid response carries `Payment-Receipt`.',
+  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.',
+}
+
+/**
+ * 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,
+}
+
+const responseRef = (name: keyof typeof responseComponents) => ({
+  $ref: `#/components/responses/${name}`,
+})
+
+/** `$ref` to the shared `402` payment-challenge response. */
+export const paymentChallengeRef = responseRef('PaymentRequired')
+
+/**
+ * Builds a single standard JSON error response with `error.code` enumerated for
+ * the status. For routes whose custom `responses` map can't go through
+ * {@link responses} — non-JSON success bodies (e.g. image, SSE) or proxy routes
+ * with upstream-shaped error bodies. `429`/`500` resolve to the shared
+ * `components.responses` entries.
+ */
+export function standardError(
+  status: keyof typeof errorCodes,
+  description: string,
+  codes?: readonly [string, ...string[]],
+): ResponsesWithResolver[string] {
+  if (status === 429) return responseRef('RateLimited')
+  if (status === 500) return responseRef('InternalError')
+  return { content: errorContent(codes ?? errorCodes[status], 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.
+ *
+ * `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`).
+ */
+export function responses<schema extends z.ZodMiniType>(
+  options: responses.Options<schema>,
+): ResponsesWithResolver {
+  const { errors, success } = options
+  const error = (status: number, fallback: string) => {
+    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 }
+  }
+  return {
+    200: {
+      content: {
+        'application/json': {
+          schema: resolver(success.schema, schemaOptions),
+          ...(success.example === undefined ? {} : { example: success.example }),
+        },
+      },
+      description: success.description,
+      headers: { ...successHeaders },
+    },
+    400: error(400, 'Invalid request.'),
+    401: error(401, 'Missing or invalid API key.'),
+    ...(errors?.[403] && { 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'),
+    500: responseRef('InternalError'),
+    502: error(502, 'Upstream data failure.'),
+  }
+}
+
+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).
+   */
+  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
+      }
+
+  /** 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.
+     */
+    errors?:
+      | {
+          /** Override for the 400 response. */
+          400?: ErrorOverride | undefined
+          /** Override for the 401 response. */
+          401?: ErrorOverride | undefined
+          /** Override for the 403 response. Setting this includes 403 in the map. */
+          403?: ErrorOverride | undefined
+          /** Override for the 404 response. Setting this includes 404 in the map. */
+          404?: ErrorOverride | undefined
+          /** Override for the 409 response. Setting this includes 409 in the map. */
+          409?: ErrorOverride | undefined
+          /** Override for the 412 response. Setting this includes 412 in the map. */
+          412?: ErrorOverride | undefined
+          /** Override for the 413 response. Setting this includes 413 in the map. */
+          413?: ErrorOverride | undefined
+          /** Override for the 415 response. Setting this includes 415 in the map. */
+          415?: ErrorOverride | undefined
+          /** Override for the 502 response. */
+          502?: ErrorOverride | undefined
+        }
+      | undefined
+    /** 200 response schema and description. */
+    success: {
+      /** Human-readable description of the success body. */
+      description: string
+      /** Optional full example body rendered for the 200 response. */
+      example?: unknown
+      /** Zod schema describing the 200 response body. */
+      schema: schema
+    }
+  }
+}
+
+/**
+ * Always false at runtime, but typed as `boolean` so route handlers can include
+ * a never-reached validation-error branch in Hono's inferred response union.
+ */
+export const narrowValidation = false as boolean
+
+/** Typed validation error response for Hono client inference. Never reached at runtime. */
+export function validationError<const code extends string>(
+  c: Context,
+  options: validationError.Options<code>,
+) {
+  return Response.error(c, { code: options.code, message: options.message, status: 400 })
+}
+
+export declare namespace validationError {
+  /** Options for building a typed validation error response. */
+  type Options<code extends string = string> = {
+    /** Stable machine-readable validation error code. */
+    code: code
+    /** Human-readable validation error message. */
+    message: string
+  }
+}
+
+/**
+ * Wrapper around `hono-openapi`'s `validator` that returns the API's standard
+ * 400 error envelope (with structured validation details) when parsing fails.
+ *
+ * Use this for every route validator instead of repeating the `result.success`
+ * ceremony per route.
+ */
+export function validate<
+  const target extends keyof ValidationTargets,
+  const schema extends z.ZodMiniType,
+>(
+  target: target,
+  schema: schema,
+  options: validate.Options,
+): MiddlewareHandler<Env, string, validate.Input<target, schema>> {
+  return validator(
+    target,
+    schema,
+    (result, c) => {
+      if (result.success) return undefined
+      return Response.error(c, {
+        code: options.code,
+        details: Response.validationDetails(result.error),
+        message: options.message,
+        status: 400,
+      })
+    },
+    // Recover `examples` zod strips from pipe/default input schemas, so every
+    // generated parameter surfaces the example attached via `z.meta(...)`.
+    schemaOptions,
+  ) as never
+}
+
+export declare namespace validate {
+  /** Hono input attached by the standard OpenAPI validator wrapper. */
+  type Input<target extends keyof ValidationTargets, schema extends z.ZodMiniType> = {
+    in: RequestInput<target, z.input<schema>>
+    out: { [key in target]: z.output<schema> }
+  }
+
+  /** Options for the standard validator helper. */
+  type Options = {
+    /** Stable machine-readable error code (e.g. `query_invalid`). */
+    code: string
+    /** Human-readable error message. */
+    message: string
+  }
+
+  /** Request input accepted by `hono/client` for a validation target. */
+  type RequestInput<target extends keyof ValidationTargets, input> = target extends 'query'
+    ? input extends object
+      ? HasRequiredKeys<input> extends true
+        ? { query: TargetInput<'query', input> }
+        : { query?: TargetInput<'query', input> | undefined }
+      : { query: input }
+    : { [key in target]: TargetInput<target, input> }
+
+  /** Converts schema input into the fetch-client input shape for a target. */
+  type TargetInput<
+    target extends keyof ValidationTargets,
+    input,
+  > = input extends ValidationTargets[target]
+    ? input
+    : {
+        [key in keyof input]: key extends keyof ValidationTargets[target]
+          ? ValidationTargets[target][key]
+          : never
+      }
+}

package/src/internal/Path.test.ts

@@ -0,0 +1,14 @@
+import * as Path from './Path.js'
+
+describe('join', () => {
+  test('normalizes URL path segments', () => {
+    expect([Path.join('/api', 'data', '42431'), Path.join('/', 'data', '/42431/'), Path.join('')])
+      .toMatchInlineSnapshot(`
+      [
+        "/api/data/42431",
+        "/data/42431",
+        "/",
+      ]
+    `)
+  })
+})

package/src/internal/Path.ts

@@ -0,0 +1,15 @@
+/** Normalizes a route prefix to a leading slash with no trailing slash. */
+export function normalize(path: string) {
+  const normalized = path.startsWith('/') ? path : `/${path}`
+  if (normalized.length > 1 && normalized.endsWith('/')) return normalized.slice(0, -1)
+  return normalized
+}
+
+/** Joins URL path segments into one normalized absolute path. */
+export function join(...segments: string[]) {
+  const path = segments
+    .flatMap((segment) => segment.split('/'))
+    .filter(Boolean)
+    .join('/')
+  return path ? `/${path}` : '/'
+}

package/src/internal/RateLimit.test.ts

@@ -0,0 +1,93 @@
+import { RateLimit, Store } from 'cadent'
+
+describe('memory', () => {
+  test('tracks fixed-window quota in a store', async () => {
+    const store = RateLimit.memory({
+      now: () => new Date('2026-05-25T00:00:30.000Z'),
+    })
+    const first = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+    const second = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+    const third = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+
+    expect(first).toMatchInlineSnapshot(`
+      {
+        "allowed": true,
+        "limit": 2,
+        "remaining": 1,
+        "reset": 1779667260,
+      }
+    `)
+    expect(second).toMatchInlineSnapshot(`
+      {
+        "allowed": true,
+        "limit": 2,
+        "remaining": 0,
+        "reset": 1779667260,
+      }
+    `)
+    expect(third).toMatchInlineSnapshot(`
+      {
+        "allowed": false,
+        "limit": 2,
+        "remaining": 0,
+        "reset": 1779667260,
+      }
+    `)
+  })
+
+  test('restarts the count when the next window opens', async () => {
+    // The window reset rides on counter expiry (the key is stable, not
+    // bucket-suffixed), so the store clock and the consume clock must agree.
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(new Date('2026-05-25T00:00:30.000Z'))
+      const store = RateLimit.memory()
+      await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+      await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+
+      vi.setSystemTime(new Date('2026-05-25T00:01:00.001Z'))
+      const next = await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+
+      expect(next).toMatchInlineSnapshot(`
+        {
+          "allowed": true,
+          "limit": 2,
+          "remaining": 1,
+          "reset": 1779667320,
+        }
+      `)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('consumes with one increment that expires at the end of the window', async () => {
+    const increments: { key: string; options: Store.Store.PutOptions | undefined }[] = []
+    const backing = Store.memory()
+    const recording = Store.from({
+      ...backing,
+      async increment(key, options) {
+        increments.push({ key, options })
+        return Store.increment(backing, key, options)
+      },
+    })
+    const store = RateLimit.memory({
+      // 30s into the minute, so 30s of the window remains.
+      now: () => new Date('2026-05-25T00:00:30.000Z'),
+      store: recording,
+    })
+
+    await store.consume({ key: 'public:anonymous', limit: { perMinute: 2 } })
+
+    expect(increments).toMatchInlineSnapshot(`
+      [
+        {
+          "key": "ratelimit:public:anonymous",
+          "options": {
+            "ttl": 30000,
+          },
+        },
+      ]
+    `)
+  })
+})