tapimo 0.2.0 → 0.4.0

package/src/apps/relay/App.ts

@@ -1,10 +1,14 @@
 import { Hono } from 'hono'
 import { createMiddleware } from 'hono/factory'
-import { Addresses } from 'viem/tempo'
+import { RpcResponse } from 'ox'
+import { Addresses, TokenId, Transaction } from 'viem/tempo'
 
 import type * as App from '../../App.js'
+import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
+import * as Fees from '../../internal/Fees.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import * as Billing from '../management/Billing.js'
 import * as Handler from '../../Handler.js'
 import * as Auth from '../../internal/Auth.js'
 import * as OpenApi from '../../internal/OpenApi.js'
@@ -43,10 +47,13 @@ export declare namespace relay {
   /** Options for the relay route group. */
   type Options = {
     feePayer?:
-      | Pick<
+      | (Pick<
           NonNullable<Handler.relay.Options['feePayer']>,
           'account' | 'feeToken' | 'name' | 'url'
-        >
+        > & {
+          /** Per-transaction fee cap (decimal USD string); orgs tighten it, never loosen. @default '1.00' */
+          txFeeLimit?: string | undefined
+        })
       | undefined
   }
 }
@@ -56,6 +63,10 @@ export declare namespace relay {
 // than closed over group locals; relay traffic is low-QPS and the viem
 // clients are memoized upstream, so per-request handler construction is cheap.
 function middleware(options: relay.Options = {}) {
+  // Platform-wide per-transaction cap; org settings tighten it, never loosen.
+  const txFeeLimit = options.feePayer
+    ? Billing.toBaseUnits(options.feePayer.txFeeLimit ?? '1.00')
+    : 0n
   return createMiddleware<App.Environment>(async (c) => {
     const verifiedTokens = c.get('verifiedTokens')
 
@@ -76,20 +87,97 @@ function middleware(options: relay.Options = {}) {
         principal?.type === 'api_key' &&
         (principal.apiKey.scopes.includes('rpc-relay:sponsor') ||
           principal.apiKey.scopes.includes(Scope.wildcard))
+      // Lifted so validation and the sponsored-token default read one value.
+      const feeToken_sponsor = options.feePayer.feeToken ?? Addresses.pathUsd
       return {
         ...options.feePayer,
-        feeToken: options.feePayer.feeToken ?? Addresses.pathUsd,
-        validate: ({ chainId }) => {
+        feeToken: feeToken_sponsor,
+        validate: async (transaction) => {
           // Allowlist the chains this deployment serves rather than denylisting
           // only mainnet: the relay resolves chainId from the request body, so
-          // the query-string chain guard never sees it. Mainnet stays closed
-          // until billing ships; nothing meters real fee-payer spend yet.
-          const id = Number(chainId)
-          return sponsorable && c.get('supportedChainIds').has(id) && !Viem.isMainnet(id)
+          // the query-string chain guard never sees it.
+          const id = Number(transaction.chainId)
+          if (!attribution || !sponsorable || !c.get('supportedChainIds').has(id)) return false
+          if (!Viem.isMainnet(id)) return true
+          // Mainnet is production-only: a sandbox key resolves chainId from the
+          // request body, so the auth-layer sandbox/mainnet guard never sees
+          // it. Refuse here, or sandbox spend would sponsor mainnet unbilled.
+          if (attribution.environment !== 'production') return false
+
+          // Enforcement reads hit the primary, never the cached replica: a
+          // stale `past_due`, a lowered limit, or another isolate's pending
+          // spend must not keep the gate open.
+          const db = Db.get(c.get('db'))
+          // Mainnet sponsorship requires an active billing source; deployments
+          // without billing configured have no rows, so mainnet stays closed.
+          // `past_due` gets its own reason: the caller must settle an invoice,
+          // not attach a card.
+          const billing = await Billing.status(db, attribution.orgId)
+          if (billing === 'past_due') return 'billing_past_due'
+          if (billing !== 'active') return 'billing_required'
+
+          const feeToken = (() => {
+            try {
+              return TokenId.toAddress(transaction.feeToken ?? feeToken_sponsor)
+            } catch {
+              return undefined
+            }
+          })()
+          const verified = feeToken
+            ? (await VerifiedTokens.read(Db.get(c.get('dbCached')), id))?.byAddress.get(feeToken.toLowerCase()) // prettier-ignore
+            : undefined
+          if (
+            !verified ||
+            verified.currency.toLowerCase() !== 'usd' ||
+            verified.decimals !== Fees.tokenDecimals
+          )
+            // prettier-ignore
+            return 'fee_token_unsupported'
+
+          // Fail closed: a transaction whose signed cap cannot be computed
+          // cannot be bounded, so it never sponsors on mainnet.
+          const feeMax = Fees.maxOf(transaction)
+          if (feeMax === undefined) return 'tx_fee_limit_exceeded'
+          const settings = await BillingSettings.get(db, attribution.orgId)
+          const cap = (() => {
+            if (settings?.txFeeLimit == null) return txFeeLimit
+            const org = Billing.toBaseUnits(settings.txFeeLimit)
+            return org < txFeeLimit ? org : txFeeLimit
+          })()
+          if (feeMax > cap) return 'tx_fee_limit_exceeded'
+          // The period spend limit is enforced atomically at recording time
+          // (`onSponsored` → `SponsoredTransactions.reserve`); a check here
+          // would be a check-then-act race a burst could slip through.
+          return true
         },
         onSponsored: async (event) => {
           if (!attribution) return
-          await SponsoredTransactions.upsert(Db.get(c.get('db')), {
+          const mainnet = Viem.isMainnet(event.chainId)
+          // Defense in depth: `validate` already refuses non-production
+          // mainnet, so reaching here with that pair is a wiring bug.
+          if (mainnet && attribution.environment !== 'production')
+            throw new RpcResponse.InvalidParamsError({ message: 'Sponsorship rejected.' })
+
+          // The cap recomputes from canonical envelope bytes, mirroring the
+          // reconciliation convention; pending rows charge it to spend limits.
+          const feeMax = Fees.maxOf(Transaction.deserialize(event.transaction as `0x76${string}`))
+          const db = Db.get(c.get('db'))
+
+          const feeToken = (() => {
+            try {
+              return event.feeToken !== undefined ? TokenId.toAddress(event.feeToken) : undefined
+            } catch {
+              return undefined
+            }
+          })()
+
+          const currency = feeToken
+            ? (await VerifiedTokens.read(Db.get(c.get('dbCached')), event.chainId))?.byAddress
+                .get(feeToken.toLowerCase())
+                ?.currency.toLowerCase()
+            : undefined
+
+          const input = {
             apiKeyId: attribution.apiKeyId,
             billable: attribution.environment === 'production',
             chainId: event.chainId,
@@ -98,9 +186,29 @@ function middleware(options: relay.Options = {}) {
             projectId: attribution.projectId,
             signPayload: event.signPayload,
             transaction: event.transaction,
-            ...(event.feeToken ? { feeToken: event.feeToken } : {}),
+            ...(currency ? { currency } : {}),
+            ...(feeMax !== undefined ? { feeMax: feeMax.toString() } : {}),
+            ...(feeToken ? { feeToken } : {}),
             ...(event.transactionHash ? { transactionHash: event.transactionHash } : {}),
-          })
+          }
+          // Re-read settings on the authoritative path: the limit may have
+          // changed since `validate`, and only mainnet spend is limited.
+          const settings = mainnet ? await BillingSettings.get(db, attribution.orgId) : undefined
+          if (settings?.spendLimit == null) return void (await SponsoredTransactions.upsert(db, input)) // prettier-ignore
+          try {
+            await SponsoredTransactions.reserve(db, input, {
+              chainIds: [Viem.chainId.mainnet],
+              max: Billing.toBaseUnits(settings.spendLimit),
+              since: Billing.periodStart(settings.period),
+            })
+          } catch (error) {
+            if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
+              throw new RpcResponse.InvalidParamsError({
+                data: { code: 'spend_limit_exceeded' },
+                message: 'Spend limit exceeded.',
+              })
+            throw error
+          }
         },
       } satisfies Handler.relay.Options['feePayer']
     })()

package/src/apps/relay/Sponsorships.test.ts

@@ -49,7 +49,7 @@ describe('finalize', () => {
     const finalized = await SponsoredTransactions.get(db, record.id)
     expect(finalized?.status).toMatchInlineSnapshot(`"finalized"`)
     // 21000 gas × 3 = 63000 base units.
-    expect(finalized?.feeAmount).toMatchInlineSnapshot(`"63000"`)
+    expect(finalized?.feeAmount).toMatchInlineSnapshot(`"1"`)
     expect(finalized?.finalizedAt).not.toBeNull()
     await db.close()
   })

package/src/apps/relay/Sponsorships.ts

@@ -10,6 +10,7 @@ import {
 import { getTransactionReceipt } from 'viem/actions'
 
 import * as Db from '../../db/Db.js'
+import * as Fees from '../../internal/Fees.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Tidx from '../../internal/Tidx.js'
 import * as Viem from '../../internal/Viem.js'
@@ -67,7 +68,7 @@ export async function finalize(db: Db.Db, options: finalize.Options): Promise<fi
 
     if (receipt) {
       // A reverted transaction still finalizes: the fee payer paid its fees.
-      const feeAmount = receipt.gasUsed * receipt.effectiveGasPrice
+      const feeAmount = Fees.fromGas(receipt.gasUsed, receipt.effectiveGasPrice)
       await SponsoredTransactions.finalize(db, row.id, {
         feeAmount: feeAmount.toString(),
         finalizedAt: now().toISOString(),

package/src/cli/Cli.test.ts

@@ -1,3 +1,4 @@
+import { Cli as incur_Cli, z } from 'incur'
 import { Cli } from 'tapimo'
 
 import * as TestApp from '../../test/App.js'
@@ -10,7 +11,7 @@ describe('from', () => {
     const fetch = mockHostedApi()
 
     try {
-      const cli = Cli.from(apiUrl, { version: '1.2.3' })
+      const cli = Cli.from(apiUrl, { docs: false, version: '1.2.3' })
       await serve(cli, ['--help'])
 
       expect(cli.name).toMatchInlineSnapshot(`"tapimo"`)
@@ -28,7 +29,7 @@ describe('from', () => {
     const fetch = mockHostedApi(TestApp.create({ db }))
 
     try {
-      const cli = Cli.from(apiUrl)
+      const cli = Cli.from(apiUrl, { docs: false })
       // `/v1/tokens?verified=true` now serves the curated verified list through
       // the standard listing endpoint, so the CLI surfaces the filter as a
       // `--verified` flag on the `v1 tokens get` command instead of routing
@@ -52,6 +53,28 @@ describe('from', () => {
       fetch.mockRestore()
     }
   })
+
+  test('mounts the docs MCP source as a command group', async () => {
+    const fetch = mockHostedApi()
+
+    // Stub remote docs MCP server: an in-process incur CLI serving `/mcp`.
+    const remote = incur_Cli.create('docs-remote', { version: '1.0.0' }).command('search', {
+      description: 'Search docs',
+      options: z.object({ query: z.string().describe('Search query') }),
+      run: (context) => ({ hits: [context.options.query] }),
+    })
+
+    try {
+      const cli = Cli.from(apiUrl, {
+        docs: { fetch: (request) => remote.fetch(request), url: 'http://docs.local/mcp' },
+      })
+      const output = await serve(cli, ['docs', 'search', '--query', 'fees', '--format', 'json'])
+
+      expect(JSON.parse(output)).toEqual({ hits: ['fees'] })
+    } finally {
+      fetch.mockRestore()
+    }
+  })
 })
 
 function mockHostedApi(app = TestApp.create()) {

package/src/cli/Cli.ts

@@ -1,29 +1,42 @@
 import { Cli as incur_Cli, Fetch, type Openapi } from 'incur'
 
+import type { mcp } from '../apps/mcp.js'
 import * as Admin from './commands/admin.js'
 
+/** Tool patterns hidden from MCP clients: super admin, partner-shaped gecko mirrors, browser session flows. */
+const excludedTools = ['admin_*', 'gecko_*', 'v1_auth_*']
+
+/** Usage guidance surfaced to MCP clients on initialize (`<cli> --mcp`). */
+const instructions =
+  'Tools mirror the hosted Tempo API. Authenticated tools accept an `authorization` input (`Bearer <api key>`). List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation.'
+
 /**
  * Creates an incur CLI backed by a hosted Tempo API, plus the super admin
- * commands (`<cli> admin …`).
+ * commands (`<cli> admin …`) and the remote Tempo docs tools (`<cli> docs …`).
  */
 export function from(url: string | URL, options: from.Options = {}) {
   const {
     description = 'Tempo API CLI',
+    docs = 'https://mcp.tempo.xyz/mcp',
     name = 'tapimo',
     openapi = 'openapi.json',
     request,
     version = '0.0.0',
   } = options
 
-  return incur_Cli
+  const cli = incur_Cli
     .create(name, {
       description,
       fetch: Fetch.fromRequest(url, request),
+      mcp: { instructions, tools: { exclude: excludedTools } },
       openapi,
       openapiConfig: options.openapiConfig ?? { mode: 'namespace' },
       version,
     })
     .command(Admin.admin)
+  if (docs !== false)
+    cli.command('docs', { description: 'Search the Tempo documentation.', mcp: docs })
+  return cli
 }
 
 export declare namespace from {
@@ -31,6 +44,8 @@ export declare namespace from {
   type Options = {
     /** CLI description. */
     description?: string | undefined
+    /** Remote docs MCP source mounted as the `docs` command group, or `false` to omit it. @default 'https://mcp.tempo.xyz/mcp' */
+    docs?: mcp.Source | false | undefined
     /** CLI name. */
     name?: string | undefined
     /** OpenAPI document source. Relative paths resolve from the API URL. */

package/src/cli/commands/admin.test.ts

@@ -1,6 +1,9 @@
 import { nanoid } from 'nanoid'
 
 import * as TestCli from '../../../test/cli.js'
+import * as Analytics from '../../analytics/Analytics.js'
+
+afterEach(() => vi.unstubAllGlobals())
 
 describe('admin', () => {
   describe('migrate', () => {
@@ -67,5 +70,85 @@ describe('admin', () => {
       expect(code).toBe(1)
       expect(envelope.error.code).toBe('migrate_failed')
     })
+
+    test('behavior: applies ClickHouse analytics migrations when configured', async () => {
+      const fetch = vi
+        .fn<typeof globalThis.fetch>()
+        .mockResolvedValue(new Response('', { status: 200 }))
+      vi.stubGlobal('fetch', fetch)
+
+      const { code, envelope } = await TestCli.run(
+        ['admin', 'migrate', '--db-schema', `t_${nanoid()}`],
+        {
+          CLICKHOUSE_DATABASE: 'tempo_api',
+          CLICKHOUSE_MIGRATE_PASSWORD: 'ddl-secret',
+          CLICKHOUSE_MIGRATE_USER: 'ddl',
+          CLICKHOUSE_URL: 'https://clickhouse.test',
+        },
+      )
+      expect(code).toBe(0)
+      expect(envelope).toEqual({ data: { analytics: true, migrated: true }, ok: true })
+      const url = new URL(String(fetch.mock.calls[0]![0]))
+      expect(url.searchParams.get('database')).toBe('tempo_api')
+      const bodies = fetch.mock.calls.map((call) => String(call[1]?.body))
+      for (const migration of Analytics.migrations) expect(bodies).toContain(migration.sql)
+    })
+
+    test('behavior: skips analytics migrations when ClickHouse env is unset or empty', async () => {
+      const fetch = vi.fn<typeof globalThis.fetch>()
+      vi.stubGlobal('fetch', fetch)
+
+      const { code, envelope } = await TestCli.run(
+        ['admin', 'migrate', '--db-schema', `t_${nanoid()}`],
+        {
+          CLICKHOUSE_DATABASE: '',
+          CLICKHOUSE_MIGRATE_PASSWORD: '',
+          CLICKHOUSE_MIGRATE_USER: '',
+          CLICKHOUSE_URL: '',
+        },
+      )
+      expect(code).toBe(0)
+      expect(envelope).toEqual({ data: { migrated: true }, ok: true })
+      expect(fetch).not.toHaveBeenCalled()
+    })
+
+    test('error: partial ClickHouse config exits 1', async () => {
+      const { code, envelope } = await TestCli.run(['admin', 'migrate'], {
+        CLICKHOUSE_MIGRATE_PASSWORD: 'ddl-secret',
+      })
+      expect(code).toBe(1)
+      expect(envelope).toEqual({
+        error: {
+          code: 'missing_clickhouse_config',
+          message:
+            'ClickHouse analytics migration is partially configured; set CLICKHOUSE_DATABASE, CLICKHOUSE_MIGRATE_USER, CLICKHOUSE_URL.',
+        },
+        ok: false,
+      })
+    })
+
+    test('error: a ClickHouse migration failure exits 1', async () => {
+      vi.stubGlobal(
+        'fetch',
+        vi.fn<typeof globalThis.fetch>().mockResolvedValue(new Response('denied', { status: 403 })),
+      )
+
+      const { code, envelope } = await TestCli.run([
+        'admin',
+        'migrate',
+        '--clickhouse-database',
+        'tempo_api',
+        '--clickhouse-migrate-password',
+        'ddl-secret',
+        '--clickhouse-migrate-user',
+        'ddl',
+        '--clickhouse-url',
+        'https://clickhouse.test',
+        '--db-schema',
+        `t_${nanoid()}`,
+      ])
+      expect(code).toBe(1)
+      expect(envelope.error.code).toBe('migrate_failed')
+    })
   })
 })

package/src/cli/commands/admin.ts

@@ -1,21 +1,53 @@
 import { Cli as incur_Cli, z } from 'incur'
 
+import * as Analytics from '../../analytics/Analytics.js'
 import * as Db from '../../db/Db.js'
 
 /**
  * Applies pending Postgres migrations, connecting directly via
  * `--database-url` or `DATABASE_URL` (never through Hyperdrive — the migrate
  * advisory lock needs session semantics); `--db-schema` scopes the session.
+ * When ClickHouse migrate credentials are configured, also applies analytics
+ * schema migrations ({@link Analytics.migrations}) over the HTTP interface.
  */
 const migrate = incur_Cli.create('migrate', {
   description: 'Apply pending database migrations.',
   env: z.object({
+    CLICKHOUSE_DATABASE: z
+      .string()
+      .optional()
+      .describe('ClickHouse database for analytics migrations.'),
+    CLICKHOUSE_MIGRATE_PASSWORD: z
+      .string()
+      .optional()
+      .describe('Password for the DDL-capable ClickHouse user.'),
+    CLICKHOUSE_MIGRATE_USER: z
+      .string()
+      .optional()
+      .describe('DDL-capable ClickHouse user for analytics migrations.'),
+    CLICKHOUSE_URL: z.string().optional().describe('ClickHouse HTTPS endpoint.'),
     DATABASE_URL: z
       .string()
       .optional()
       .describe('Postgres connection string. Used when --database-url is omitted.'),
   }),
   options: z.object({
+    clickhouseDatabase: z
+      .string()
+      .optional()
+      .describe('ClickHouse database. Overrides CLICKHOUSE_DATABASE.'),
+    clickhouseMigratePassword: z
+      .string()
+      .optional()
+      .describe('ClickHouse DDL password. Overrides CLICKHOUSE_MIGRATE_PASSWORD.'),
+    clickhouseMigrateUser: z
+      .string()
+      .optional()
+      .describe('ClickHouse DDL user. Overrides CLICKHOUSE_MIGRATE_USER.'),
+    clickhouseUrl: z
+      .string()
+      .optional()
+      .describe('ClickHouse HTTPS endpoint. Overrides CLICKHOUSE_URL.'),
     databaseUrl: z
       .string()
       .optional()
@@ -29,13 +61,25 @@ const migrate = incur_Cli.create('migrate', {
         code: 'missing_database_url',
         message: 'Set --database-url or DATABASE_URL to the Postgres connection string.',
       })
+
+    const analytics = clickhouseConfig({
+      database: c.options.clickhouseDatabase ?? c.env.CLICKHOUSE_DATABASE,
+      password: c.options.clickhouseMigratePassword ?? c.env.CLICKHOUSE_MIGRATE_PASSWORD,
+      url: c.options.clickhouseUrl ?? c.env.CLICKHOUSE_URL,
+      user: c.options.clickhouseMigrateUser ?? c.env.CLICKHOUSE_MIGRATE_USER,
+    })
+    if (analytics?.missing)
+      return c.error({
+        code: 'missing_clickhouse_config',
+        message: `ClickHouse analytics migration is partially configured; set ${analytics.missing.join(', ')}.`,
+      })
+
     const db = Db.postgres({
       connectionString,
       ...(c.options.dbSchema ? { schema: c.options.dbSchema } : {}),
     })
     try {
       await db.migrate()
-      return { migrated: true }
     } catch (error) {
       /* v8 ignore next */
       const message = error instanceof Error ? error.message : 'Migration failed.'
@@ -46,6 +90,19 @@ const migrate = incur_Cli.create('migrate', {
     } finally {
       await db.close()
     }
+    if (!analytics) return { migrated: true }
+
+    try {
+      await Analytics.clickhouse(analytics.options).migrate()
+    } catch (error) {
+      /* v8 ignore next */
+      const message = error instanceof Error ? error.message : 'Migration failed.'
+      return c.error({
+        code: 'migrate_failed',
+        message,
+      })
+    }
+    return { analytics: true, migrated: true }
   },
 })
 
@@ -58,3 +115,34 @@ export const admin = incur_Cli
     description: 'Super admin commands for a Tempo API deployment.',
   })
   .command(migrate)
+
+/**
+ * Resolves ClickHouse migrate config. Credentials gate the migration (absent
+ * → skip); empty values count as unset since CI renders missing secrets as
+ * empty strings. Partial config returns the missing variable names instead.
+ */
+function clickhouseConfig(input: {
+  database?: string | undefined
+  password?: string | undefined
+  url?: string | undefined
+  user?: string | undefined
+}):
+  | { missing: readonly string[]; options?: undefined }
+  | { missing?: undefined; options: Analytics.clickhouse.Options }
+  | undefined {
+  const database = input.database || undefined
+  const password = input.password || undefined
+  const url = input.url || undefined
+  const user = input.user || undefined
+  if (password === undefined && user === undefined) return undefined
+  if (database === undefined || password === undefined || url === undefined || user === undefined)
+    return {
+      missing: [
+        ...(database === undefined ? ['CLICKHOUSE_DATABASE'] : []),
+        ...(password === undefined ? ['CLICKHOUSE_MIGRATE_PASSWORD'] : []),
+        ...(user === undefined ? ['CLICKHOUSE_MIGRATE_USER'] : []),
+        ...(url === undefined ? ['CLICKHOUSE_URL'] : []),
+      ],
+    }
+  return { options: { database, password, url, user } }
+}