tapimo 0.1.0 → 0.3.0

package/src/apps/relay/Sponsorships.ts

@@ -0,0 +1,306 @@
+import type { Hex } from 'ox'
+import { TxEnvelopeTempo } from 'ox/tempo'
+import {
+  type Address,
+  type Client,
+  type EIP1193RequestFn,
+  type TransactionReceipt,
+  TransactionReceiptNotFoundError,
+} from 'viem'
+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'
+
+/**
+ * Runs one finalization pass over pending sponsored transactions: rows with a
+ * receipt finalize with the actual fee (`gasUsed × effectiveGasPrice`, in
+ * fee-token base units); rows still unmined past the pending TTL fail, as do
+ * hash-less fill intents the TTL outlives. Rows whose receipt lookup errors
+ * persist past the error TTL fail so they cannot monopolize every batch.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Finalization options.
+ * @returns Counters for the pass.
+ */
+export async function finalize(db: Db.Db, options: finalize.Options): Promise<finalize.Result> {
+  const {
+    batchSize = 100,
+    getClient,
+    now = () => new Date(),
+    pendingTtlMs = 3_600_000,
+    receiptErrorTtlMs = 86_400_000,
+  } = options
+
+  const rows = await SponsoredTransactions.listPending(db, { limit: batchSize })
+  const result = { failed: 0, finalized: 0, pending: 0 }
+
+  for (const row of rows) {
+    // Fill intents carry no hash until reconciliation matches them on-chain;
+    // here only the TTL can settle them.
+    if (row.transactionHash === null) {
+      if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
+        await SponsoredTransactions.fail(db, row.id, now().toISOString())
+        result.failed++
+      } else result.pending++
+      continue
+    }
+
+    let receipt: TransactionReceipt | null
+    try {
+      receipt = await getTransactionReceipt(getClient(row.chainId), {
+        hash: row.transactionHash as Hex.Hex,
+      })
+    } catch (error) {
+      // Unmined transactions surface as a typed not-found; let the TTL decide.
+      if (error instanceof TransactionReceiptNotFoundError) receipt = null
+      else {
+        if (Date.parse(row.createdAt) + receiptErrorTtlMs <= now().getTime()) {
+          await SponsoredTransactions.fail(db, row.id, now().toISOString())
+          result.failed++
+        } else result.pending++
+        continue
+      }
+    }
+
+    if (receipt) {
+      // A reverted transaction still finalizes: the fee payer paid its fees.
+      const feeAmount = Fees.fromGas(receipt.gasUsed, receipt.effectiveGasPrice)
+      await SponsoredTransactions.finalize(db, row.id, {
+        feeAmount: feeAmount.toString(),
+        finalizedAt: now().toISOString(),
+      })
+      result.finalized++
+    } else if (Date.parse(row.createdAt) + pendingTtlMs <= now().getTime()) {
+      await SponsoredTransactions.fail(db, row.id, now().toISOString())
+      result.failed++
+    } else result.pending++
+  }
+
+  return result
+}
+
+export declare namespace finalize {
+  /** Options for {@link finalize}. */
+  type Options = {
+    /** Maximum pending rows processed per pass. @default 100 */
+    batchSize?: number | undefined
+    /** Client resolver keyed by the row's chain id. */
+    getClient: (chainId: number) => Client
+    /** Clock; injectable for tests. */
+    now?: (() => Date) | undefined
+    /** Age after which an unmined sponsorship fails. @default 1 hour */
+    pendingTtlMs?: number | undefined
+    /** Age after which repeated receipt lookup errors fail a row. @default 24 hours */
+    receiptErrorTtlMs?: number | undefined
+  }
+
+  /** Counters returned by one finalization pass. */
+  type Result = {
+    /** Rows marked failed (unmined past the pending TTL). */
+    failed: number
+    /** Rows finalized with an actual fee. */
+    finalized: number
+    /** Rows left pending (unmined, or receipt lookup errored within the error TTL). */
+    pending: number
+  }
+}
+
+/**
+ * Runs one reconciliation pass over pending fill intents (rows with no
+ * transaction hash): fetches the fee payer's recent on-chain transactions
+ * from TIDX, recomputes each candidate's fee-payer sign payload, and fills
+ * matching intents' hashes so the receipt pass can finalize them. Query or
+ * candidate errors leave intents for the next pass.
+ *
+ * @param db - The database holding `sponsored_transactions`.
+ * @param options - Reconciliation options.
+ * @returns Counters for the pass.
+ */
+export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<reconcile.Result> {
+  const {
+    batchSize = 100,
+    candidateCap = 500,
+    failedIntentTtlMs = 86_400_000,
+    feePayer,
+    getClient,
+    getTidx,
+    skewMs = 120_000,
+  } = options
+
+  const intents = await SponsoredTransactions.listIntents(db, {
+    failedSince: new Date(Date.now() - failedIntentTtlMs).toISOString(),
+    limit: batchSize,
+  })
+  const result = { matched: 0, scanned: 0 }
+  if (intents.length === 0) return result
+
+  const chains = new Map<number, SponsoredTransactions.Record[]>()
+  for (const intent of intents) chains.set(intent.chainId, [...(chains.get(intent.chainId) ?? []), intent]) // prettier-ignore
+
+  for (const [chainId, rows] of chains) {
+    const bySignPayload = new Map(rows.map((row) => [row.signPayload, row]))
+    // The intent set bounds the scan window: no cursor state to persist.
+    const since = new Date(
+      Math.min(...rows.map((row) => Date.parse(row.createdAt))) - skewMs,
+    ).toISOString()
+
+    let candidates: readonly globalThis.Record<string, unknown>[]
+    try {
+      // Dynamic filter values; the tidx client's query type wants literals.
+      const fetched = await getTidx(chainId).fetch({
+        chainId,
+        query:
+          `SELECT hash, "from" FROM txs WHERE fee_payer = '${feePayer.toLowerCase()}' AND block_timestamp >= '${since}' ORDER BY block_timestamp ASC LIMIT ${candidateCap}` as string,
+      })
+      candidates = fetched.rows
+    } catch {
+      // Indexer outage must not fail intents; retry on the next pass.
+      continue
+    }
+
+    for (const candidate of candidates) {
+      if (bySignPayload.size === 0) break
+      const hash = candidate['hash'] as Hex.Hex | undefined
+      const sender = candidate['from'] as Address | undefined
+      if (!hash || !sender) continue
+      result.scanned++
+      try {
+        const serialized = await getRawTransaction(getClient(chainId), hash)
+        if (!serialized?.startsWith(TxEnvelopeTempo.serializedType)) continue
+        const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(
+          TxEnvelopeTempo.deserialize(serialized as TxEnvelopeTempo.Serialized),
+          { sender },
+        )
+        const intent = bySignPayload.get(signPayload)
+        if (!intent) continue
+        await SponsoredTransactions.assignTransactionHash(db, intent.id, hash)
+        bySignPayload.delete(signPayload)
+        result.matched++
+      } catch {
+        // Unresolvable candidate (lookup error, malformed envelope): skip it.
+      }
+    }
+  }
+
+  return result
+}
+
+export declare namespace reconcile {
+  /** Options for {@link reconcile}. */
+  type Options = {
+    /** Maximum intents considered per pass. @default 100 */
+    batchSize?: number | undefined
+    /** Maximum on-chain candidates fetched per chain per pass. @default 500 */
+    candidateCap?: number | undefined
+    /** How long failed intents remain reconciliation candidates. @default 24 hours */
+    failedIntentTtlMs?: number | undefined
+    /** Fee payer address whose on-chain transactions are candidates. */
+    feePayer: Address
+    /** Client resolver keyed by the intent's chain id. */
+    getClient: (chainId: number) => Client
+    /** TIDX client resolver keyed by the intent's chain id. */
+    getTidx: (chainId: number) => Tidx.Client
+    /** Lookback slack before the oldest intent's creation. @default 2 minutes */
+    skewMs?: number | undefined
+  }
+
+  /** Counters returned by one reconciliation pass. */
+  type Result = {
+    /** Intents matched to an on-chain transaction. */
+    matched: number
+    /** On-chain candidates inspected. */
+    scanned: number
+  }
+}
+
+/**
+ * Fetches a mined transaction's canonical envelope bytes.
+ * `eth_getRawTransactionByHash` is a node extension absent from viem's typed
+ * RPC schema, hence the request-fn narrowing.
+ */
+function getRawTransaction(client: Client, hash: Hex.Hex) {
+  type Request = EIP1193RequestFn<
+    [
+      {
+        Method: 'eth_getRawTransactionByHash'
+        Parameters: readonly [Hex.Hex]
+        ReturnType: Hex.Hex | null
+      },
+    ]
+  >
+  return (client.request as Request)({ method: 'eth_getRawTransactionByHash', params: [hash] })
+}
+
+/**
+ * Builds a scheduled sponsorship finalizer bound to a database and RPC config.
+ * A host runtime drives {@link createFinalizer.Finalizer.tick} on a timer (a
+ * Cloudflare `scheduled` cron handler, a self-host `setInterval`, …); each
+ * tick reconciles fill intents (when `feePayer` + `tidx` are configured) and
+ * runs one {@link finalize} pass, with memoized per-chain clients.
+ */
+export function createFinalizer(options: createFinalizer.Options): createFinalizer.Finalizer {
+  const clients = new Map<number, Viem.getClient.ReturnType>()
+  const getClient = (chainId: number) => {
+    let client = clients.get(chainId)
+    if (!client) {
+      client = Viem.getClient({ chainId: chainId as Viem.ChainId, rpc: options.rpc })
+      clients.set(chainId, client)
+    }
+    return client
+  }
+  const getTidx = options.tidx
+    ? Tidx.createGetClient({ defaultChainId: options.defaultChainId, tidx: options.tidx })
+    : undefined
+  const feePayer = options.feePayer
+
+  return {
+    async tick() {
+      // Resolve per tick so Workers factories build a fresh Hyperdrive-pooled
+      // connection each run.
+      const db = Db.get(options.db)
+      // Reconcile first so freshly matched intents finalize in the same tick.
+      const reconciled =
+        feePayer && getTidx
+          ? await reconcile(db, {
+              batchSize: options.batchSize,
+              feePayer,
+              getClient,
+              getTidx: (chainId) => getTidx(chainId as Viem.ChainId),
+            })
+          : { matched: 0, scanned: 0 }
+      const finalized = await finalize(db, {
+        batchSize: options.batchSize,
+        getClient,
+        now: options.now,
+        pendingTtlMs: options.pendingTtlMs,
+      })
+      return { ...finalized, ...reconciled }
+    },
+  }
+}
+
+export declare namespace createFinalizer {
+  /** Options for {@link createFinalizer}. */
+  type Options = Pick<finalize.Options, 'batchSize' | 'now' | 'pendingTtlMs'> & {
+    /** Database holding sponsorship rows, or a factory resolved per tick (Workers/Hyperdrive). */
+    db: Db.Source
+    /** Default chain id for the TIDX client resolver. */
+    defaultChainId?: Viem.ChainId | undefined
+    /** Fee payer address whose on-chain transactions reconcile fill intents; omit to skip reconciliation. */
+    feePayer?: Address | undefined
+    /** RPC options for the receipt-lookup clients. */
+    rpc?: Viem.getClient.Rpc | undefined
+    /** TIDX query client options for intent reconciliation; omit to skip reconciliation. */
+    tidx?: Tidx.getClient.Tidx | undefined
+  }
+
+  /** A scheduled sponsorship finalizer. */
+  type Finalizer = {
+    /** Runs one reconcile + finalize pass. */
+    tick(): Promise<finalize.Result & reconcile.Result>
+  }
+}

package/src/apps/relay/index.ts

@@ -0,0 +1,2 @@
+export { relay } from './App.js'
+export * as Sponsorships from './Sponsorships.js'

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 operator
- * commands (`<cli> admin …`).
+ * Creates an incur CLI backed by a hosted Tempo API, plus the super 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,15 +90,59 @@ 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 }
   },
 })
 
 /**
- * Operator commands that run against a deployment's infrastructure rather
+ * Super admin commands that run against a deployment's infrastructure rather
  * than the hosted API (database migrations, …).
  */
 export const admin = incur_Cli
   .create('admin', {
-    description: 'Operator commands for a Tempo API deployment.',
+    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 } }
+}