tapimo 0.13.0 → 0.15.0

package/src/Handler.ts

@@ -5,7 +5,6 @@ import type { UnionToIntersection } from './handlers/internal/types.js'
 import * as RequestListener from './handlers/internal/requestListener.js'
 
 export { relay } from './handlers/relay.js'
-export * as Multisig from './handlers/internal/multisig.js'
 
 /**
  * A request handler. Generic over the underlying Hono app shape so chained

package/src/OpenApi.contract.test.ts

@@ -0,0 +1,195 @@
+import { validate } from '@scalar/openapi-parser'
+
+import * as TestApp from '../test/App.js'
+import * as Mcp from './apps/mcp.js'
+
+type JsonObject = Record<string, unknown>
+
+const methods = ['delete', 'get', 'head', 'options', 'patch', 'post', 'put', 'trace'] as const
+
+function array(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+function object(value: unknown): JsonObject | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  return value as JsonObject
+}
+
+function operations(document: JsonObject) {
+  return ['paths', 'webhooks'].flatMap((surface) => {
+    const paths = object(document[surface]) ?? {}
+    return Object.entries(paths).flatMap(([path, item]) => {
+      const pathItem = object(item) ?? {}
+      return methods.flatMap((method) => {
+        const operation = object(pathItem[method])
+        const name = surface === 'paths' ? path : `${surface}:${path}`
+        return operation ? ([[name, method, operation, pathItem]] as const) : []
+      })
+    })
+  })
+}
+
+function jsonMedia(content: unknown) {
+  const entries = object(content)
+  if (!entries || !Object.hasOwn(entries, 'application/json'))
+    return { present: false, schema: undefined }
+  return {
+    present: true,
+    schema: object(object(entries['application/json'])?.['schema']),
+  }
+}
+
+function resolvePointer(document: JsonObject, pointer: string): unknown {
+  if (!pointer.startsWith('#/')) return undefined
+  return pointer
+    .slice(2)
+    .split('/')
+    .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+    .reduce<unknown>((value, part) => object(value)?.[part], document)
+}
+
+function resolveObject(document: JsonObject, value: unknown): JsonObject | undefined {
+  const current = object(value)
+  if (!current || typeof current['$ref'] !== 'string') return current
+  return object(resolvePointer(document, current['$ref']))
+}
+
+function references(value: unknown): readonly string[] {
+  if (Array.isArray(value)) return value.flatMap(references)
+  const current = object(value)
+  if (!current) return []
+  return Object.entries(current).flatMap(([key, item]) =>
+    key === '$ref' && typeof item === 'string' ? [item] : references(item),
+  )
+}
+
+function missingFieldExamples(
+  document: JsonObject,
+  value: unknown,
+  path: string,
+  audit = false,
+  seen: ReadonlySet<string> = new Set(),
+): readonly string[] {
+  if (Array.isArray(value))
+    return value.flatMap((item) => missingFieldExamples(document, item, path, audit, seen))
+  const current = object(value)
+  if (!current) return []
+  const documented = 'example' in current || 'examples' in current
+  const missing = audit && !documented ? [path] : []
+  if (typeof current['$ref'] === 'string') {
+    if (seen.has(current['$ref'])) return []
+    return missingFieldExamples(
+      document,
+      resolvePointer(document, current['$ref']),
+      path,
+      audit,
+      new Set([...seen, current['$ref']]),
+    )
+  }
+
+  const properties = object(current['properties']) ?? {}
+  return [
+    ...missing,
+    ...Object.entries(properties).flatMap(([name, schema]) =>
+      missingFieldExamples(document, schema, `${path}.${name}`, true, seen),
+    ),
+    ...['allOf', 'anyOf', 'items', 'oneOf'].flatMap((name) =>
+      missingFieldExamples(document, current[name], path, false, seen),
+    ),
+  ]
+}
+
+async function document() {
+  const app = TestApp.create({ webhook: { supportedChainIds: [4217] } })
+  const fetch = app.fetch.bind(app)
+  app.route('/', Mcp.mcp({ fetch }))
+  const response = await app.request('/openapi.json')
+  expect(response.status).toBe(200)
+  const value = (await response.json()) as JsonObject
+  expect(operations(value).length).toBeGreaterThan(0)
+  return value
+}
+
+describe('OpenAPI contract', () => {
+  test('uses unique operation ids and valid component references', async () => {
+    const spec = await document()
+    const validation = await validate(spec)
+    const routes = operations(spec)
+    const ids = routes.map(([, , operation]) => operation['operationId'])
+
+    expect(ids.every((id) => typeof id === 'string' && id.length > 0)).toBe(true)
+    expect(new Set(ids).size).toBe(ids.length)
+    expect(references(spec).filter((reference) => !resolvePointer(spec, reference))).toStrictEqual(
+      [],
+    )
+    expect(validation.errors ?? []).toStrictEqual([])
+    expect(validation.valid).toBe(true)
+  })
+
+  test('names JSON request and success models', async () => {
+    const spec = await document()
+    const unnamed: string[] = []
+
+    for (const [path, method, operation] of operations(spec)) {
+      const request = jsonMedia(resolveObject(spec, operation['requestBody'])?.['content'])
+      // MPP and MCP bodies are owned by their external protocols.
+      const protocolOwned = path.startsWith('/v1/mpp/') || path === '/mcp'
+      if (request.present && !request.schema && !protocolOwned)
+        unnamed.push(`${method} ${path} request schema`)
+      else if (request.schema && !protocolOwned && typeof request.schema['$ref'] !== 'string')
+        unnamed.push(`${method} ${path} request`)
+
+      const responses = object(operation['responses']) ?? {}
+      for (const [status, response] of Object.entries(responses)) {
+        if (!status.startsWith('2')) continue
+        const media = jsonMedia(resolveObject(spec, response)?.['content'])
+        if (media.present && !media.schema && !protocolOwned)
+          unnamed.push(`${method} ${path} response ${status} schema`)
+        else if (media.schema && !protocolOwned && typeof media.schema['$ref'] !== 'string')
+          unnamed.push(`${method} ${path} response ${status}`)
+      }
+    }
+
+    expect(unnamed).toStrictEqual([])
+  })
+
+  test('documents examples in JSON success models', async () => {
+    const spec = await document()
+    const missing: string[] = []
+
+    for (const [path, method, operation, pathItem] of operations(spec)) {
+      for (const parameter of [
+        ...array(pathItem['parameters']),
+        ...array(operation['parameters']),
+      ]) {
+        const resolved = resolveObject(spec, parameter)
+        const schema = object(resolved?.['schema'])
+        if (resolved && !schema)
+          missing.push(`${method} ${path} parameter ${String(resolved['name'])} schema`)
+        else if (
+          resolved &&
+          schema &&
+          !('example' in resolved) &&
+          !('examples' in resolved) &&
+          !('example' in schema) &&
+          !('examples' in schema)
+        )
+          missing.push(`${method} ${path} parameter ${String(resolved?.['name'])}`)
+      }
+
+      const responses = object(operation['responses']) ?? {}
+      for (const [status, response] of Object.entries(responses)) {
+        if (!status.startsWith('2')) continue
+        const media = jsonMedia(resolveObject(spec, response)?.['content'])
+        // MCP owns this external protocol envelope rather than Tempo's REST model conventions.
+        if (path === '/mcp') continue
+        if (media.present && !media.schema) missing.push(`${method} ${path} ${status} schema`)
+        else if (media.schema)
+          missing.push(...missingFieldExamples(spec, media.schema, `${method} ${path} ${status}`))
+      }
+    }
+
+    expect([...new Set(missing)]).toStrictEqual([])
+  })
+})

package/src/Scope.ts

@@ -36,13 +36,14 @@ export const catalog = [
     selfServe: true,
   },
   {
-    description: 'Read organization funding transfers, deposit addresses, and deposits.',
-    scope: 'funding:read',
-    selfServe: false,
+    description: 'Read organization route transfers, deposit addresses, and deposits.',
+    scope: 'routes:read',
+    selfServe: true,
   },
+  // Routes writes require Tempo approval and provisioning through the super admin.
   {
-    description: 'Create funding transfers and register their source transactions.',
-    scope: 'funding:write',
+    description: 'Create route transfers and register their source transactions.',
+    scope: 'routes:write',
     selfServe: false,
   },
   {
@@ -66,6 +67,17 @@ export const catalog = [
     scope: 'mpp:write',
     selfServe: true,
   },
+  {
+    description: 'Read wallet and Earn vault reward eligibility associations.',
+    scope: 'rewards:read',
+    selfServe: false,
+  },
+  {
+    description:
+      'Legacy reward eligibility write scope retained for existing keys; registration requires wildcard access.',
+    scope: 'rewards:write',
+    selfServe: false,
+  },
   {
     description: 'Fill and submit transactions through the relay.',
     scope: 'rpc-relay:read',

package/src/Webhooks.ts

@@ -5,6 +5,6 @@ export * from './internal/Webhooks.js'
 
 // Re-export the webhook resource's zod schemas so consumers can validate and
 // type delivery bodies: `Webhooks.schema.Envelope` (a discriminated union on
-// `type`), plus the per-event `TransferEvent` / `TransactionEvent` / `PingEvent`
-// payloads. Infer a type with `z.infer<typeof Webhooks.schema.Envelope>`.
+// `type`), plus the per-event payload schemas such as `RoutesTransferEvent`.
+// Infer a type with `z.infer<typeof Webhooks.schema.Envelope>`.
 export { enrichEventData, eventTypes, scanBlock, schema } from './apps/data/routes/webhooks.js'

package/src/admin/App.test.ts

@@ -32,6 +32,16 @@ describe('create', () => {
         }),
         new Request('http://admin/organizations/org_x/members'),
         new Request('http://admin/organizations/org_x/projects'),
+        new Request('http://admin/routes/summary'),
+        new Request('http://admin/routes/support'),
+        new Request('http://admin/routes/transfers'),
+        new Request('http://admin/routes/transfers/rtr_x'),
+        new Request('http://admin/routes/deposit-addresses'),
+        new Request('http://admin/routes/deposit-addresses/rda_x'),
+        new Request('http://admin/routes/deposits'),
+        new Request('http://admin/routes/deposits/rdp_x'),
+        new Request('http://admin/subsidies/transactions'),
+        new Request('http://admin/subsidies/routes'),
         new Request('http://admin/verified-tokens?chainId=42431', {
           body: JSON.stringify({ tokens: [] }),
           headers: { 'content-type': 'application/json' },
@@ -52,7 +62,10 @@ describe('create', () => {
       // The shell inlines `identity: null` so the SPA renders login on first paint.
       const html = await shell.text()
       const json = html.match(/window\.__TEMPO_API_CONFIG__=({.*?})<\/script>/)?.[1]
-      expect(JSON.parse(json!)).toEqual({ auth: { identity: null, loginUrl: '/login' } })
+      expect(JSON.parse(json!)).toEqual({
+        auth: { identity: null, loginUrl: '/login' },
+        rewards: { signerAddress: '0x6000000000000000000000000000000000000006' },
+      })
       const assetPath = html.match(/\.\/(assets\/[^"]+\.js)/)?.[1]
       expect((await app.request(`http://admin/${assetPath}`)).status).toBe(200)
     })
@@ -82,7 +95,15 @@ describe('create', () => {
   describe('cache policy', () => {
     test('every response is no-store (admin data is per-principal and mutating)', async () => {
       const { app } = TestAdmin.setup()
-      for (const path of ['/scopes', '/api-keys', '/organizations', '/config.json']) {
+      for (const path of [
+        '/scopes',
+        '/api-keys',
+        '/organizations',
+        '/routes/summary',
+        '/routes/support',
+        '/subsidies/transactions',
+        '/config.json',
+      ]) {
         const response = await app.request(`http://admin${path}`)
         expect(response.headers.get('cache-control')).toBe('no-store')
       }
@@ -131,6 +152,9 @@ describe('create', () => {
             "loginUrl": "/login",
             "logoutUrl": "/logout",
           },
+          "rewards": {
+            "signerAddress": "0x6000000000000000000000000000000000000006",
+          },
         }
       `)
     })
@@ -146,6 +170,9 @@ describe('create', () => {
               "email": "ops@tempo.xyz",
             },
           },
+          "rewards": {
+            "signerAddress": "0x6000000000000000000000000000000000000006",
+          },
         }
       `)
     })
@@ -178,6 +205,7 @@ describe('create', () => {
           loginUrl: 'https://sso/login',
           logoutUrl: 'https://sso/logout',
         },
+        rewards: { signerAddress: '0x6000000000000000000000000000000000000006' },
       })
     })
 

package/src/admin/App.ts

@@ -1,13 +1,16 @@
 import { type Context, Hono, type Next } from 'hono'
 import { HTTPException } from 'hono/http-exception'
 import { requestId, type RequestIdVariables } from 'hono/request-id'
-import type { Chain } from 'viem'
+import type { Address, Chain } from 'viem'
 
 import * as ApiKey from '../ApiKey.js'
 import type * as Assets from '../Assets.js'
 import type * as Analytics from '../analytics/Analytics.js'
 import * as Db from '../db/Db.js'
 import * as AdminAuditLogs from '../db/tables/adminAuditLogs.js'
+import type * as Email from '../internal/Email.js'
+import type * as Metrics from '../Metrics.js'
+import * as RateLimit from '../internal/RateLimit.js'
 import type * as Store from '../internal/Store.js'
 import * as Response from '../internal/Response.js'
 import * as Viem from '../internal/Viem.js'
@@ -16,8 +19,11 @@ import * as Zones from '../apps/Zones.js'
 import { apiKeys } from './apps/api-keys.js'
 import { earlyAccess } from './apps/early-access.js'
 import { earnVaults } from './apps/earn-vaults.js'
+import { routes } from './apps/routes.js'
+import { routesSupport } from './apps/routes-support.js'
 import { organizations } from './apps/organizations.js'
 import { scopes } from './apps/scopes.js'
+import { subsidies } from './apps/subsidies.js'
 import { verifiedTokens } from './apps/verified-tokens.js'
 import * as Ui from './ui.generated.js'
 
@@ -38,12 +44,18 @@ export type Environment = {
     basePath: string
     /** Authoritative Postgres store, or a per-request factory. Resolve at the leaf with `Db.get`. */
     db: Db.Source
+    /** Transactional email sender, when configured. */
+    email: Email.Sender | undefined
     /** Gets a Tempo RPC client for a chain id. */
     getClient: Viem.GetClient
     /** The admin identity, or `null` when unauthenticated (gated routes reject). */
     identity: Identity | null
     /** KV state store backing API-key records (mint/list/revoke). */
     kv: { store: Store.State }
+    /** Shared rate-limit counter used by admin-triggered side effects. */
+    rateLimit: RateLimit.Store | undefined
+    /** Bounded operational metrics backend. */
+    metrics: Metrics.Metrics | undefined
     /** Zone chains available to admin routes. */
     zones: readonly Chain[]
   }
@@ -58,6 +70,7 @@ export function create(options: create.Options) {
 
   const zones = options.zones === true ? Zones.chains : (options.zones ?? [])
   const getClient = Viem.createGetClient({ rpc: options.rpc, zones })
+  const rateLimit = options.rateLimit ? RateLimit.memory(options.rateLimit) : undefined
 
   // `false` (disabled) collapses to `undefined` so only a real config surfaces
   // `loginUrl`/`logoutUrl` in `/config.json`.
@@ -78,29 +91,37 @@ export function create(options: create.Options) {
     c.set('assets', options.assets)
     c.set('basePath', c.req.routePath.replace(/\*$/, '').replace(/\/$/, ''))
     c.set('db', options.db)
+    c.set('email', options.email)
     c.set('getClient', getClient)
     c.set('kv', options.kv)
+    c.set('metrics', options.metrics)
+    c.set('rateLimit', rateLimit)
     c.set('zones', zones)
     c.set('identity', await identify(c.req.raw))
-    return next()
+    try {
+      return await next()
+    } finally {
+      options.metrics?.flush()
+    }
   })
 
-  // Auth contract the UI reads (identity + sign-in/out URLs). Served at
+  // Bootstrap contract the UI reads. Served at
   // `/config.json` and inlined into the shell, so the UI reads it synchronously.
-  function authConfig(identity: Identity | null) {
+  function bootstrapConfig(identity: Identity | null) {
     return {
       auth: {
         identity,
         ...(ui?.loginUrl ? { loginUrl: ui.loginUrl } : {}),
         ...(ui?.logoutUrl ? { logoutUrl: ui.logoutUrl } : {}),
       },
+      rewards: { signerAddress: options.rewardsSignerAddress },
     }
   }
 
   // Renders the public SPA shell: stamps its hydration-safe base and auth
   // placeholders with request values. `<` is escaped to keep the config script.
   const serveShell = (c: Context<Environment>) => {
-    const config = JSON.stringify(authConfig(c.get('identity'))).replaceAll('<', '\\u003c')
+    const config = JSON.stringify(bootstrapConfig(c.get('identity'))).replaceAll('<', '\\u003c')
     return c.html(
       Ui.shell
         .replace(
@@ -138,10 +159,14 @@ export function create(options: create.Options) {
     '/early-access/*',
     '/earn/verified-vaults',
     '/earn/verified-vaults/*',
+    '/routes',
+    '/routes/*',
     '/organizations',
     '/organizations/*',
     '/scopes',
     '/scopes/*',
+    '/subsidies',
+    '/subsidies/*',
     '/verified-tokens',
     '/verified-tokens/*',
   ] as const
@@ -171,12 +196,15 @@ export function create(options: create.Options) {
     })
 
   const routed = app
-    .get('/config.json', (c) => c.json(authConfig(c.get('identity')), 200))
+    .get('/config.json', (c) => c.json(bootstrapConfig(c.get('identity')), 200))
     .route('/api-keys', apiKeys())
     .route('/early-access', earlyAccess())
     .route('/earn/verified-vaults', earnVaults())
+    .route('/routes/support', routesSupport())
+    .route('/routes', routes())
     .route('/organizations', organizations())
     .route('/scopes', scopes())
+    .route('/subsidies', subsidies())
     .route('/verified-tokens', verifiedTokens())
 
   // Any other non-API GET renders the public SPA shell (catch-all last, so data
@@ -241,6 +269,8 @@ export declare namespace create {
      * (`() => Db.postgres(...)`) on Workers.
      */
     db: Db.Source
+    /** Transactional email sender used for organization invitations. */
+    email?: Email.Sender | undefined
     /**
      * Extracts the verified admin identity from a request, or `null` to deny.
      * Must only return an identity for an already-authenticated request (a
@@ -252,6 +282,12 @@ export declare namespace create {
      * `kv` option), provisioned against by the `/api-keys` routes.
      */
     kv: { store: Store.State }
+    /** Metrics backend for admin operational signals. */
+    metrics?: Metrics.Metrics | undefined
+    /** Public address used by the reward signer service. */
+    rewardsSignerAddress: Address
+    /** Shared counter store used to rate limit admin-triggered side effects. */
+    rateLimit?: RateLimit.memory.Options | undefined
     /** Tempo RPC options used by onchain verification. */
     rpc?: Viem.getClient.Rpc | undefined
     /**