tapimo 0.2.0 → 0.4.0

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

@@ -6,6 +6,7 @@ import type * as App from '../../../App.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
 import * as Cursor from '../../../internal/Cursor.js'
+import * as Fees from '../../../internal/Fees.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
@@ -25,13 +26,6 @@ import { decodeTransactionType, embedFeeTokens, schema as txSchema } from './tra
 /** Example transaction hash surfaced in OpenAPI docs. */
 const exampleHash = '0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665'
 
-// Tempo gas prices are denominated in attodollars (10^-18 USD) while fee-token
-// balances use 6 decimals (microdollars, 10^-6 USD), so the fee charged to the
-// fee payer — in the fee token's base units — is
-// `ceil(gasUsed * effectiveGasPrice / 10^12)` (ceiling division). Mirrors
-// `calc_gas_balance_spending` in tempoxyz/tempo.
-const feeScalingFactor = 10n ** 12n
-
 /**
  * Computes the fee charged to the fee payer, in the fee token's base units, from
  * the receipt's `gasUsed` and decimal `effectiveGasPrice`. Returns undefined
@@ -39,8 +33,7 @@ const feeScalingFactor = 10n ** 12n
  */
 function computeFeeAmount(gasUsed: number | undefined, effectiveGasPrice: string | undefined) {
   if (gasUsed === undefined || effectiveGasPrice === undefined) return undefined
-  const product = BigInt(gasUsed) * BigInt(effectiveGasPrice)
-  return ((product + feeScalingFactor - 1n) / feeScalingFactor).toString()
+  return Fees.fromGas(BigInt(gasUsed), BigInt(effectiveGasPrice)).toString()
 }
 
 /** Zod schemas owned by the receipt handlers. */

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

@@ -96,7 +96,7 @@ describe('POST /rpc', () => {
     }
   })
 
-  test('routes anonymous requests to the public RPC without basic auth', async () => {
+  test('allows eth-prefixed methods anonymously', async () => {
     const fetch = mockRpc()
 
     try {
@@ -109,7 +109,7 @@ describe('POST /rpc', () => {
 
       const response = await app.fetch(
         new Request('http://tempo-api.test/rpc/testnet', {
-          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_fillTransaction' }),
           method: 'POST',
         }),
       )
@@ -122,6 +122,82 @@ describe('POST /rpc', () => {
     }
   })
 
+  test('requires an API key for non-eth methods', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create()
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'tempo_fundAddress' }),
+          method: 'POST',
+        }),
+      )
+      const body = (await response.json()) as Record<string, unknown>
+      const { requestId, ...stable } = body
+
+      expect(response.status).toMatchInlineSnapshot(`401`)
+      expect(typeof requestId).toMatchInlineSnapshot(`"string"`)
+      expect(stable).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "api_key_missing",
+            "message": "Missing API key",
+          },
+        }
+      `)
+      expect(fetch.calls).toMatchInlineSnapshot(`[]`)
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('requires an API key when a batch includes a private method', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create()
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc', {
+          body: JSON.stringify([
+            { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
+            { id: 2, jsonrpc: '2.0', method: 'tempo_fundAddress' },
+          ]),
+          method: 'POST',
+        }),
+      )
+      const body = (await response.json()) as { error?: { code?: unknown } }
+
+      expect(response.status).toMatchInlineSnapshot(`401`)
+      expect(body.error?.code).toMatchInlineSnapshot(`"api_key_missing"`)
+      expect(fetch.calls).toMatchInlineSnapshot(`[]`)
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('allows API keys to call private methods', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create()
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'tempo_fundAddress' }),
+          headers: { 'tempo-api-key': TestApp.key.token },
+          method: 'POST',
+        }),
+      )
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(fetch.calls[0]?.body).toMatchInlineSnapshot(
+        `"{"id":1,"jsonrpc":"2.0","method":"tempo_fundAddress"}"`,
+      )
+    } finally {
+      fetch.restore()
+    }
+  })
+
   test('uses the requested chain id for upstream URL resolution', async () => {
     const fetch = mockRpc()
 

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

@@ -143,9 +143,22 @@ export function rpc() {
       summary: 'Call JSON-RPC',
       tags: ['RPC'],
     }),
-    (c) => {
+    async (c) => {
       if (Auth.narrowAccess) return Auth.accessError(c)
 
+      if (requiresApiKey(c)) {
+        const body = await c.req.raw
+          .clone()
+          .json()
+          .catch(() => undefined)
+        if (!isPublicRequest(body))
+          return Response.error(c, {
+            code: 'api_key_missing',
+            message: 'Missing API key',
+            status: 401,
+          })
+      }
+
       const chainId = resolveChainId(c)
       if (!chainId)
         return Response.error(c, {
@@ -161,6 +174,23 @@ export function rpc() {
   )
 }
 
+function requiresApiKey(c: Context<App.Environment>) {
+  if (!c.get('auth')) return false
+  const principal = Auth.getPrincipal(c)
+  return principal?.type !== 'api_key' && principal?.type !== 'super_admin'
+}
+
+function isPublicRequest(body: unknown): boolean {
+  const requests = Array.isArray(body) ? body : [body]
+  return requests.length > 0 && requests.every((request) => isPublicMethod(request))
+}
+
+function isPublicMethod(request: unknown): boolean {
+  if (!request || typeof request !== 'object') return false
+  const method = (request as Record<string, unknown>)['method']
+  return typeof method === 'string' && method.startsWith('eth_')
+}
+
 async function passthrough(
   c: Context<App.Environment>,
   chainId: z.output<typeof Schema.ChainId>,

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

@@ -1151,7 +1151,7 @@ describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
   // the real keyset/`toBlock` SQL and decode path end to end — no fabricated rows.
   const realTidx = Tidx.getClient({
     chainId: 42431,
-    tidx: { baseUrl: 'https://tidx.tempo.xyz', basicAuth: process.env.VITE_TIDX_BASIC_AUTH },
+    tidx: { baseUrl: 'https://tidx.tempo.xyz', basicAuth: process.env.TIDX_BASIC_AUTH },
   })
   // The monitoring scanners (`log:emitted`/`block:created`/`transaction:included`)
   // read the same immutable historical window over real RPC (chain 42431 →

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

@@ -533,7 +533,7 @@ export namespace schema {
         .string()
         .check(
           z.describe('Webhook subscription ID (`wh_…`).'),
-          z.meta({ examples: ['wh_abc123'] }),
+          z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
         ),
       lastDeliveryAt: z
         .optional(z.iso.datetime())
@@ -594,7 +594,10 @@ export namespace schema {
         ),
       id: z
         .string()
-        .check(z.describe('Webhook delivery ID (`whd_…`).'), z.meta({ examples: ['whd_abc123'] })),
+        .check(
+          z.describe('Webhook delivery ID (`whd_…`).'),
+          z.meta({ examples: ['whd_001718668800000_C1yJkk7CuML98HFthEDk9PsY'] }),
+        ),
       requestUrl: z
         .string()
         .check(
@@ -620,7 +623,7 @@ export namespace schema {
         .string()
         .check(
           z.describe('Subscription ID (`wh_…`) this delivery belongs to.'),
-          z.meta({ examples: ['wh_abc123'] }),
+          z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
         ),
     })
     .check(z.describe('One attempt by Tempo to deliver an event to your webhook URL.'))
@@ -901,7 +904,7 @@ export namespace schema {
       .string()
       .check(
         z.describe('Subscription ID (`wh_…`) that produced this delivery.'),
-        z.meta({ examples: ['wh_abc123'] }),
+        z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
       ),
   }
 
@@ -1075,7 +1078,7 @@ export namespace schema {
           .string()
           .check(
             z.describe('Webhook subscription ID (`wh_…`).'),
-            z.meta({ examples: ['wh_001718668800000_V1StGXR8Z5jdHi6B2myTq'] }),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
       })
       .check(z.describe('Path parameters for a webhook subscription request.'))
@@ -1158,13 +1161,13 @@ export namespace schema {
           .string()
           .check(
             z.describe('Delivery ID (`whd_…`) you want Tempo to replay.'),
-            z.meta({ examples: ['whd_001718668800000_8oQ2pVmZ4kKxWnLcRfTbN'] }),
+            z.meta({ examples: ['whd_001718668800000_C1yJkk7CuML98HFthEDk9PsY'] }),
           ),
         id: z
           .string()
           .check(
             z.describe('Webhook subscription ID (`wh_…`).'),
-            z.meta({ examples: ['wh_001718668800000_V1StGXR8Z5jdHi6B2myTq'] }),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
       })
       .check(z.describe('Path parameters for retrying a webhook delivery.'))
@@ -1209,7 +1212,7 @@ export namespace schema {
           .string()
           .check(
             z.describe('ID of the webhook subscription that was deleted.'),
-            z.meta({ examples: ['wh_abc123'] }),
+            z.meta({ examples: ['wh_001718668800000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
       })
       .check(z.describe('Confirmation that the webhook subscription was deleted.'))

package/src/apps/docs/App.ts

@@ -1,18 +1,16 @@
+import type { Context } from 'hono'
 import { Hono } from 'hono'
-import { Handler as vocs_Handler } from 'vocs/server'
+import type { Handler as vocs_Handler } from 'vocs/server'
 
 import type * as App from '../../App.js'
 import * as Metadata from '../metadata.js'
-import openrpcSpec from '../../openrpc.json' with { type: 'json' }
-import { pilatFontFaces } from './fonts.js'
-import { logoUrl } from './logo.js'
 
 /**
  * The docs route group: the Vocs API reference served at the app root.
  *
  * ```ts
  * import { docs } from 'tapimo/docs'
- * App.create(options).route('/', data()).route('/', platform()).route('/', docs())
+ * App.create(options).route('/', data()).route('/', management()).route('/', docs())
  * ```
  *
  * The group registers no routes itself: it carries a reference factory (via
@@ -23,21 +21,26 @@ import { logoUrl } from './logo.js'
  *
  * Lives in the `tapimo/docs` subpath (never re-exported from `tapimo/apps`) so
  * the Vocs renderer and its multi-MB icon/font data are bundled only by
- * deployments that actually serve docs.
+ * deployments that actually serve docs. Even then the renderer loads lazily on
+ * the first docs request (see `reference.ts`), so API traffic and isolate
+ * startup never pay for it.
  */
 export function docs(options: docs.Options = {}) {
   return Metadata.attach(new Hono<App.Environment>(), {
-    docs: ({ spec }) =>
-      vocs_Handler.openApi(
-        {
-          // Inline the OpenRPC doc so vocs expands it without a self-subrequest
-          // (see `inlineOpenrpc`); the public `/openapi.json` keeps the URL ref.
-          spec: () => spec().then(inlineOpenrpc),
-          sidebar: { collapsed: true },
-          vocs: { logoUrl, title: 'Tempo API Reference', ...options },
-        },
-        { css, fallback: 'next' },
-      ),
+    docs: ({ spec }) => {
+      // Memoized across requests: all docs traffic shares one handler.
+      let handler: Promise<Hono> | undefined
+      return new Hono<App.Environment>().get('*', async (c, next) => {
+        handler ??= import('./reference.js').then((m) =>
+          m.create({ mount: mountFromRoutePath(c.req.routePath), spec, vocs: options }),
+        )
+        const response = await (await handler).fetch(c.req.raw, c.env, executionCtx(c))
+        // Inner 404 means "not a docs route" (`fallback: 'next'` semantics):
+        // defer to the host app's later routes / JSON `notFound`.
+        if (response.status === 404) return next()
+        return response
+      })
+    },
   })
 }
 
@@ -46,91 +49,17 @@ export declare namespace docs {
   type Options = NonNullable<Parameters<typeof vocs_Handler.openApi>[0]['vocs']>
 }
 
-/**
- * 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}).
- */
-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;
+/** Derives the host mount prefix from Hono's matched `routePath` (`/api/*` → `/api`, `/*` → ``). */
+function mountFromRoutePath(routePath: string) {
+  return routePath.replace(/\*+$/, '').replace(/\/+$/, '')
 }
 
-[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;
-}`
-
-/**
- * Returns a shallow copy of `spec` with the JSON-RPC passthrough operation's
- * `x-openrpc` replaced by the inline OpenRPC document, for the docs handler.
- *
- * Vocs expands `x-openrpc` at request time. A URL reference (as kept in the
- * public `/openapi.json` by `App.create`'s `applyOpenrpcLink`) would make the
- * docs worker fetch its own `/openrpc.json` — a self-subrequest that is
- * unreliable on Cloudflare Workers and silently falls back to a single,
- * unexpanded operation. Inlining the committed artifact keeps expansion
- * deterministic across local and deployed environments, without bloating the
- * public spec. Only the affected path/op are cloned; the rest of the (large)
- * document is shared by reference.
- */
-function inlineOpenrpc<spec extends { paths: Record<string, unknown> }>(spec: spec): spec {
-  const paths: Record<string, unknown> = {}
-  for (const [pathname, item] of Object.entries(spec.paths)) {
-    let next = item
-    if (isRecord(item))
-      for (const [method, op] of Object.entries(item))
-        if (isRpcOperation(op)) next = { ...item, [method]: { ...op, 'x-openrpc': openrpcSpec } }
-    paths[pathname] = next
+// `c.executionCtx` throws outside Workers (tests, Node); docs rendering never
+// uses `waitUntil`, so absence is fine.
+function executionCtx(c: Context) {
+  try {
+    return c.executionCtx
+  } catch {
+    return undefined
   }
-  return { ...spec, paths }
-}
-
-// The JSON-RPC passthrough's operation id, set by its route definition and
-// targeted by `App.create`'s `applyOpenrpcLink`.
-function isRpcOperation(op: unknown): op is Record<string, unknown> {
-  return isRecord(op) && op['operationId'] === 'rpcRequest'
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === 'object' && !Array.isArray(value)
 }

package/src/apps/docs/reference.ts

@@ -0,0 +1,132 @@
+import { Hono } from 'hono'
+import { Handler as vocs_Handler } from 'vocs/server'
+
+import type * as App from '../../App.js'
+import openrpcSpec from '../../openrpc.json' with { type: 'json' }
+import type { docs } from './App.js'
+import { pilatFontFaces } from './fonts.js'
+import { logoUrl } from './logo.js'
+
+/**
+ * Builds the Vocs reference handler. Loaded via dynamic import on the first
+ * docs request (see `docs()` in `App.ts`), keeping the multi-MB renderer off
+ * isolate startup.
+ */
+export function create(options: create.Options): Hono {
+  const { mount, spec, vocs } = options
+  const handler = vocs_Handler.openApi(
+    {
+      // Inline the OpenRPC doc so vocs expands it without a self-subrequest
+      // (see `inlineOpenrpc`); the public `/openapi.json` keeps the URL ref.
+      spec: () => spec().then(inlineOpenrpc),
+      sidebar: { collapsed: true },
+      vocs: { logoUrl, title: 'Tempo API Reference', ...vocs },
+    },
+    { css, fallback: 'next' },
+  )
+  if (!mount) return handler
+  // Re-mount under the host prefix so the handler's `routePath`-derived mount
+  // (asset link bases, known-route checks) matches a direct `.route()` mount.
+  return new Hono().route(mount, handler)
+}
+
+export declare namespace create {
+  /** Options for building the reference handler. */
+  type Options = {
+    /** Host mount prefix derived from the wrapper's matched `routePath` (`''` at root). */
+    mount: string
+    /** Memoized OpenAPI document builder — the same document served at `/openapi.json`. */
+    spec: App.create.DocsContext['spec']
+    /** Vocs reference options (theme, top navigation, logo, socials, …). */
+    vocs: docs.Options
+  }
+}
+
+/**
+ * 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}).
+ */
+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;
+}`
+
+/**
+ * Returns a shallow copy of `spec` with the JSON-RPC passthrough operation's
+ * `x-openrpc` replaced by the inline OpenRPC document, for the docs handler.
+ *
+ * Vocs expands `x-openrpc` at request time. A URL reference (as kept in the
+ * public `/openapi.json` by `App.create`'s `applyOpenrpcLink`) would make the
+ * docs worker fetch its own `/openrpc.json` — a self-subrequest that is
+ * unreliable on Cloudflare Workers and silently falls back to a single,
+ * unexpanded operation. Inlining the committed artifact keeps expansion
+ * deterministic across local and deployed environments, without bloating the
+ * public spec. Only the affected path/op are cloned; the rest of the (large)
+ * document is shared by reference.
+ */
+function inlineOpenrpc<spec extends { paths: Record<string, unknown> }>(spec: spec): spec {
+  const paths: Record<string, unknown> = {}
+  for (const [pathname, item] of Object.entries(spec.paths)) {
+    let next = item
+    if (isRecord(item))
+      for (const [method, op] of Object.entries(item))
+        if (isRpcOperation(op)) next = { ...item, [method]: { ...op, 'x-openrpc': openrpcSpec } }
+    paths[pathname] = next
+  }
+  return { ...spec, paths }
+}
+
+// The JSON-RPC passthrough's operation id, set by its route definition and
+// targeted by `App.create`'s `applyOpenrpcLink`.
+function isRpcOperation(op: unknown): op is Record<string, unknown> {
+  return isRecord(op) && op['operationId'] === 'rpcRequest'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}

package/src/apps/index.ts

@@ -1,3 +1,4 @@
-export { data } from './data/index.js'
-export { platform } from './platform/index.js'
+export { data, FundingRouteProviders } from './data/index.js'
+export { management } from './management/index.js'
+export { mcp } from './mcp.js'
 export { relay } from './relay/index.js'