tapimo 0.5.3 → 0.7.0

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

@@ -21,7 +21,7 @@ import * as Receipts from './receipts.js'
 import * as Transactions from './transactions.js'
 import * as Transfers from './transfers.js'
 
-/** Default cap on active subscriptions per owner, overridable via `webhook.maxPerOwner`. */
+/** Default cap on live subscriptions per owner, overridable via `webhook.maxPerOwner`. */
 const defaultMaxPerOwner = 100
 
 /**
@@ -1317,10 +1317,13 @@ export function webhooks(options: webhooks.Options = {}) {
           responses: OpenApi.responses({
             errors: {
               400: {
-                codes: ['chain_id_unsupported'],
-                description: 'Webhook subscriptions do not support Zone chains.',
+                codes: ['body_invalid', 'chain_id_unsupported', 'filters_invalid', 'url_invalid'],
+                description: 'The request, destination, filters, or chain are invalid.',
+              },
+              403: {
+                codes: ['limit_exceeded'],
+                description: 'You have reached the webhook subscription limit.',
               },
-              403: 'You have reached the webhook subscription limit.',
             },
             success: {
               description:
@@ -1347,12 +1350,9 @@ export function webhooks(options: webhooks.Options = {}) {
 
           const body = c.req.valid('json')
           const chainId = body.chainId ?? c.get('chainId')
-          if (c.get('zones').has(chainId))
-            return Response.error(c, {
-              code: 'chain_id_unsupported',
-              message: 'Webhook subscriptions do not support Zone chains.',
-              status: 400,
-            })
+          const supportedChainIds = new Set(webhook.supportedChainIds)
+          if (!supportedChainIds.has(chainId))
+            return Response.unsupportedChainId(c, chainId, supportedChainIds)
 
           try {
             const subscription = await Webhooks.createSubscription(
@@ -1373,7 +1373,7 @@ export function webhooks(options: webhooks.Options = {}) {
               200,
             )
           } catch (cause) {
-            return mutationError(c, cause)
+            return createMutationError(c, cause)
           }
         },
       )
@@ -1747,6 +1747,16 @@ export function webhooks(options: webhooks.Options = {}) {
           operationId: 'updateWebhook',
           responses: OpenApi.responses({
             errors: {
+              400: {
+                codes: [
+                  'body_invalid',
+                  'destination_transition_invalid',
+                  'filters_invalid',
+                  'param_invalid',
+                  'url_invalid',
+                ],
+                description: 'The update, destination, or filters are invalid.',
+              },
               404: {
                 description: 'No webhook subscription was found for that ID.',
                 codes: ['webhook_not_found'],
@@ -1798,7 +1808,7 @@ export function webhooks(options: webhooks.Options = {}) {
               200,
             )
           } catch (cause) {
-            return mutationError(c, cause)
+            return updateMutationError(c, cause)
           }
         },
       )
@@ -1987,13 +1997,14 @@ export async function poll(options: poll.Options): Promise<poll.Result> {
       let accepted: readonly [number, number] | undefined
       let failed = false
       for (const item of page.items) {
-        // Enrich `token:transfer` rows with best-effort token metadata so
-        // downstream destinations (Slack human amounts, richer `url`/`betterstack`
-        // payloads) can render `amount` in token units. Non-fatal on failure.
+        // Token metadata is best-effort for webhooks: transfers use it for display,
+        // while transactions expose fee-token references without blocking delivery.
         const data =
           eventType === 'token:transfer'
             ? await withTokenMetadata(item.data, { cache: cache_metadata, chainId, client })
-            : item.data
+            : eventType === 'transaction:included'
+              ? await withFeeTokenMetadata(item.data, { cache: cache_metadata, chainId, client })
+              : item.data
         const envelope = Webhooks.buildEnvelope({
           blockNumber: item.cursor[0],
           createdAt: now(),
@@ -2106,27 +2117,45 @@ async function withTokenMetadata(
   const address = (data as Record<string, unknown>)['address']
   if (typeof address !== 'string') return data
   const token = await resolveTokenMetadata(address, deps)
-  return token ? { ...(data as Record<string, unknown>), token } : data
+  return token
+    ? {
+        ...(data as Record<string, unknown>),
+        token: { decimals: token.decimals, symbol: token.symbol },
+      }
+    : data
+}
+
+/** Core RPC metadata needed by a humanized token reference. */
+type TokenMetadata = {
+  currency: string
+  decimals: number
+  name: string
+  symbol: string
 }
 
 /**
- * Resolves a token's `{ symbol, decimals }` via `token.getMetadata`, memoized per
+ * Resolves core token metadata via `token.getMetadata`, memoized per
  * `(chainId, address)` with a short TTL so a busy transfer stream shares one RPC
- * lookup per token. Returns `undefined` on any failure — metadata is a rendering
+ * lookup per token. Returns `undefined` on any failure; metadata is a rendering
  * nicety, never a delivery blocker.
  */
 async function resolveTokenMetadata(
   address: string,
   deps: { cache: Store.Store; chainId: number; client: Viem.getClient.ReturnType },
-): Promise<{ decimals: number; symbol: string } | undefined> {
+): Promise<TokenMetadata | undefined> {
   try {
     return await Store.memoize(
       async () => {
         const meta = await deps.client.token.getMetadata({ token: address as `0x${string}` })
-        return { decimals: meta.decimals, symbol: meta.symbol }
+        return {
+          currency: meta.currency,
+          decimals: meta.decimals,
+          name: meta.name,
+          symbol: meta.symbol,
+        }
       },
       {
-        key: `webhook:token-meta:v1:${deps.chainId}:${address}`,
+        key: `webhook:token-meta:v2:${deps.chainId}:${address}`,
         store: deps.cache,
         ttl: Ttl.minutes(5),
       },
@@ -2137,6 +2166,69 @@ async function resolveTokenMetadata(
   }
 }
 
+/** Returns the address from an unenriched or enriched fee-token value. */
+function feeTokenAddress(value: unknown) {
+  if (typeof value === 'string') return value
+  if (typeof value !== 'object' || value === null) return undefined
+  const address = (value as Record<string, unknown>)['address']
+  return typeof address === 'string' ? address : undefined
+}
+
+/** Replaces an address-valued fee token with its resolved reference, or omits it on failure. */
+function withResolvedFeeToken(data: Record<string, unknown>, metadata: Map<string, TokenMetadata>) {
+  const address = feeTokenAddress(data['feeToken'])
+  if (!address) return data
+  const result = { ...data }
+  delete result['feeToken']
+  const token = metadata.get(address.toLowerCase())
+  if (token) result['feeToken'] = { address, ...token }
+  return result
+}
+
+/** Adds best-effort fee-token references to a transaction and its embedded receipt. */
+async function withFeeTokenMetadata(
+  data: unknown,
+  deps: {
+    cache: Store.Store
+    chainId: number
+    client: Viem.getClient.ReturnType
+  },
+): Promise<unknown> {
+  if (typeof data !== 'object' || data === null) return data
+  const transaction = data as Record<string, unknown>
+  const meta = transaction['meta']
+  const receipt =
+    typeof meta === 'object' && meta !== null
+      ? (meta as Record<string, unknown>)['receipt']
+      : undefined
+  const addresses = new Set<string>()
+  const transactionAddress = feeTokenAddress(transaction['feeToken'])
+  if (transactionAddress) addresses.add(transactionAddress.toLowerCase())
+  if (typeof receipt === 'object' && receipt !== null) {
+    const receiptAddress = feeTokenAddress((receipt as Record<string, unknown>)['feeToken'])
+    if (receiptAddress) addresses.add(receiptAddress.toLowerCase())
+  }
+  if (addresses.size === 0) return data
+
+  const resolved = await Promise.all(
+    [...addresses].map(
+      async (address) => [address, await resolveTokenMetadata(address, deps)] as const,
+    ),
+  )
+  const metadata = new Map(
+    resolved.filter((entry): entry is readonly [string, TokenMetadata] => entry[1] !== undefined),
+  )
+  const result = withResolvedFeeToken(transaction, metadata)
+  if (typeof receipt !== 'object' || receipt === null) return result
+  return {
+    ...result,
+    meta: {
+      ...(meta as Record<string, unknown>),
+      receipt: withResolvedFeeToken(receipt as Record<string, unknown>, metadata),
+    },
+  }
+}
+
 /** Returns the live RPC head block number for the chain. */
 export async function getRpcHead(client: Viem.getClient.ReturnType): Promise<number> {
   return Number(await client.getBlockNumber())
@@ -2883,8 +2975,8 @@ const txFields = {
  * Scans included transactions over the confirmed window. Each block is fetched
  * with full transactions via `eth_getBlockByNumber(n, true)`; receipts are
  * fetched lazily (only when a `status`/`gasUsed`/`feePayer` filter needs them).
- * The delivered payload reuses `Transactions.humanizeTransaction`, so it is
- * byte-identical to the read endpoint.
+ * The delivered payload starts from `Transactions.humanizeTransaction`; the
+ * poller then resolves its fee-token references.
  */
 async function scanTxs(options: {
   cache: ChainCache
@@ -2921,13 +3013,19 @@ async function scanTxs(options: {
       if (!matchesTx(tx, f, includeCalls, receipt, timestamp, n)) continue
       const parsed = Transactions.schema.Rpc.Transaction.safeParse(tx)
       if (!parsed.success) continue
-      let data = Transactions.humanizeTransaction(parsed.data)
+      let data: Record<string, unknown> = Transactions.humanizeTransaction(parsed.data)
       // Embed the humanized receipt under `meta.receipt`, matching the read
       // endpoint's `include=receipt` shape so `data` stays a valid envelope.
       if (includeReceipt && receipt) {
         const r = Receipts.schema.Rpc.Receipt.safeParse(receipt)
         if (r.success)
-          data = { ...data, meta: { ...data.meta, receipt: Receipts.humanizeReceipt(r.data) } }
+          data = {
+            ...data,
+            meta: {
+              ...(data['meta'] as Record<string, unknown>),
+              receipt: Receipts.humanizeReceipt(r.data),
+            },
+          }
       }
       items.push({ cursor: [n, index], data })
     }
@@ -3040,7 +3138,7 @@ function redactDestination(destination: WebhookDestination.Destination) {
   return destination
 }
 
-function mutationError(c: Context<App.Environment>, cause: unknown) {
+function createMutationError(c: Context<App.Environment>, cause: unknown) {
   if (cause instanceof Webhooks.InvalidUrlError)
     return Response.error(c, { code: 'url_invalid', message: cause.message, status: 400 })
   if (cause instanceof Webhooks.InvalidFilterError)
@@ -3055,6 +3153,25 @@ function mutationError(c: Context<App.Environment>, cause: unknown) {
   return Response.upstream(c, cause)
 }
 
+function updateMutationError(c: Context<App.Environment>, cause: unknown) {
+  if (cause instanceof Webhooks.InvalidDestinationTransitionError)
+    return Response.error(c, {
+      code: 'destination_transition_invalid',
+      message: cause.message,
+      status: 400,
+    })
+  if (cause instanceof Webhooks.InvalidUrlError)
+    return Response.error(c, { code: 'url_invalid', message: cause.message, status: 400 })
+  if (cause instanceof Webhooks.InvalidFilterError)
+    return Response.error(c, {
+      code: 'filters_invalid',
+      details: cause.details,
+      message: cause.message,
+      status: 400,
+    })
+  return Response.upstream(c, cause)
+}
+
 function notFound(c: Context<App.Environment>) {
   return Response.error(c, {
     code: 'webhook_not_found',

package/src/apps/index.ts

@@ -1,4 +1,5 @@
-export { data, FundingQuoteProviders } from './data/index.js'
+export { data, FundingQuoteProviders, FxOracle } from './data/index.js'
 export { management } from './management/index.js'
 export { mcp } from './mcp.js'
+export { mpp } from './mpp/index.js'
 export { relay } from './relay/index.js'

package/src/apps/management/App.ts

@@ -6,6 +6,7 @@ import * as Metadata from '../metadata.js'
 
 import { apiKeys } from './routes/api-keys.js'
 import { billing } from './routes/billing.js'
+import { faucet } from './routes/faucet.js'
 import { invitations } from './routes/invitations.js'
 import { inviteLinks } from './routes/invite-links.js'
 import { me } from './routes/me.js'
@@ -14,6 +15,8 @@ import { orgs } from './routes/orgs.js'
 import { projects } from './routes/projects.js'
 import { scopes } from './routes/scopes.js'
 import { usage } from './routes/usage.js'
+import { verifiedTokenRequests } from './routes/verified-token-requests.js'
+import { webhooks } from './routes/webhooks.js'
 
 /**
  * Minimal transactional email sender. Cloudflare deployments wrap the Email
@@ -105,6 +108,7 @@ export function management(options: management.Options = {}) {
     })
     .route('/', apiKeys({ enabled: options.apiKeys !== false }))
     .route('/', billing())
+    .route('/', faucet())
     .route('/', invitations())
     .route('/', inviteLinks())
     .route('/', me())
@@ -113,6 +117,8 @@ export function management(options: management.Options = {}) {
     .route('/', projects())
     .route('/', scopes())
     .route('/', usage())
+    .route('/', verifiedTokenRequests())
+    .route('/', webhooks({ webhook: options.webhook === false ? undefined : options.webhook }))
   return Metadata.attach(app, openapi)
 }
 
@@ -125,6 +131,8 @@ export declare namespace management {
     billing?: Billing | undefined
     /** Transactional email sender for management emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
     email?: Email | undefined
+    /** Webhook capability shared with the data group and host poller; omit or pass false to disable management. */
+    webhook?: App.Webhook | false | undefined
   }
 }
 
@@ -145,6 +153,7 @@ const openapi = {
   tags: [
     { name: 'API Keys', description: 'Credentials for accessing the Tempo API.' },
     { name: 'Billing', description: 'Organization billing backed by Stripe.' },
+    { name: 'Faucet', description: 'Test token funding for Tempo testnet accounts.' },
     { name: 'Invitations', description: 'Pending organization invitations.' },
     { name: 'Invite Links', description: 'Reusable organization invite links.' },
     { name: 'Members', description: 'Organization team membership.' },
@@ -152,6 +161,8 @@ const openapi = {
     { name: 'Projects', description: 'Application workspaces within an organization.' },
     { name: 'Usage', description: 'Request and sponsorship usage for organizations.' },
     { name: 'Users', description: 'Users on the Tempo Platform.' },
+    { name: 'Verified Token Requests', description: 'Organization requests to add tokens to the curated verified list.' }, // prettier-ignore
+    { name: 'Webhooks', description: 'Organization webhook subscriptions.' },
   ],
   'x-tagGroups': [
     {
@@ -167,6 +178,8 @@ const openapi = {
         'Projects',
         'Usage',
         'Users',
+        'Verified Token Requests',
+        'Webhooks',
       ],
     },
   ],

package/src/apps/management/routes/api-keys.test.ts

@@ -671,3 +671,17 @@ describe('keys', () => {
     expect(response.status).toBe(403)
   })
 })
+
+describe('early access', () => {
+  test('does not require an early-access grant', async () => {
+    const app = createApp()
+    const cookie = await session(app)
+    const { org, project } = await fixture(app, cookie)
+
+    const minted = await app.request(
+      `/v1/orgs/${org.id}/projects/${project.id}/api-keys`,
+      json('POST', cookie, { scopes: ['data:read'] }),
+    )
+    expect(minted.status).toBe(200)
+  })
+})

package/src/apps/management/routes/api-keys.ts

@@ -1,6 +1,8 @@
 import { type Context, Hono } from 'hono'
 import * as z from 'zod/mini'
 
+import * as Analytics from '../../../analytics/Analytics.js'
+import * as RequestEvents from '../../../analytics/tables/requestEvents.js'
 import * as ApiKeys from '../../../ApiKeys.js'
 import type * as App from '../../../App.js'
 import * as Db from '../../../db/Db.js'
@@ -43,6 +45,12 @@ export namespace schema {
           z.describe('Opaque key id (`key_…`).'),
           z.meta({ examples: ['key_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
         ),
+      lastUsedAt: z
+        .optional(z.string())
+        .check(
+          z.describe('When the key last authenticated a request (ISO 8601).'),
+          z.meta({ examples: ['2026-07-21T12:34:56.000Z'] }),
+        ),
       name: z
         .optional(z.string())
         .check(z.describe('Human-readable key name.'), z.meta({ examples: ['CI'] })),
@@ -374,7 +382,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
           })
           return c.json(
             Response.validated(schema.listApiKeys.Response, {
-              data: records.map(serializeKey),
+              data: await serializeKeys(c, records),
             }),
             200,
           )
@@ -435,7 +443,7 @@ export function apiKeys(options: apiKeys.Options = {}) {
           })
           return c.json(
             Response.validated(schema.listOrgApiKeys.Response, {
-              data: records.map(serializeKey),
+              data: await serializeKeys(c, records),
             }),
             200,
           )
@@ -505,14 +513,30 @@ export declare namespace apiKeys {
   }
 }
 
+/** Enriches key records with their latest authenticated request timestamp. */
+async function serializeKeys(c: Context<App.Environment>, records: readonly ApiKeys.Record[]) {
+  const source = c.get('analytics')
+  if (!source || records.length === 0) return records.map((record) => serializeKey(record))
+  const lastUsedAt = new Map(
+    (
+      await RequestEvents.readLastUsedAt(
+        Analytics.get(source),
+        records.map(({ id }) => id),
+      )
+    ).map((usage) => [usage.apiKeyId, usage.lastUsedAt]),
+  )
+  return records.map((record) => serializeKey(record, lastUsedAt.get(record.id)))
+}
+
 /** Projects a persisted record onto the management key shape (no rate limits, no token). */
-function serializeKey(record: ApiKeys.Record) {
+function serializeKey(record: ApiKeys.Record, lastUsedAt?: string) {
   return {
     createdAt: record.createdAt,
     ...(record.createdBy === undefined ? {} : { createdBy: record.createdBy }),
     environment: record.environment,
     ...(record.expiresAt === undefined ? {} : { expiresAt: record.expiresAt }),
     id: record.id,
+    ...(lastUsedAt === undefined ? {} : { lastUsedAt }),
     ...(record.name === undefined ? {} : { name: record.name }),
     orgId: record.orgId,
     ...(record.projectId === undefined ? {} : { projectId: record.projectId }),