tapimo 0.4.0 → 0.4.3

package/src/internal/FundingRoutes.ts

@@ -307,7 +307,9 @@ export type ChainRef = ReturnType<typeof formatChain> | typeof destinationChain
 export type TokenAmount = ReturnType<typeof resolveSourceAmount>
 
 /** Normalized token reference passed to provider adapters. */
-export type TokenRef = ReturnType<typeof formatDestinationToken> | ReturnType<typeof formatSourceToken>
+export type TokenRef =
+  | ReturnType<typeof formatDestinationToken>
+  | ReturnType<typeof formatSourceToken>
 
 /** A normalized funding route candidate returned by route discovery. */
 export type RouteCandidate = ReturnType<typeof formatRouteCandidate>
@@ -411,6 +413,64 @@ export type QuoteProbeResult = {
   }
 }
 
+/** Token reference attached to a normalized provider fee. */
+export type ProviderQuoteFeeToken = {
+  /** Token contract address on its chain. */
+  address: string
+  /** CAIP-2 chain id for the fee token. */
+  chainId: string
+  /** Number of decimal places used by the fee token. */
+  decimals: number
+  /** Fee token ticker symbol. */
+  symbol: string
+}
+
+/** Normalized fee amount returned by a provider quote. */
+export type ProviderQuoteFee = {
+  /** Fee amount in the fee token's base units. */
+  amount: string
+  /** Provider-estimated USD value of the fee. */
+  amountUsd: string | null
+  /** Fee as basis points of the quoted input, when available. */
+  bps: number | null
+  /** Token in which the fee amount is denominated. */
+  token: ProviderQuoteFeeToken
+}
+
+/** Input passed to a provider for one explicit, depositor-specific quote. */
+export type ProviderQuoteInput = {
+  /** Address that would submit the funding transaction. */
+  depositor: string
+  /** Optional destination recipient; providers default it to the depositor. */
+  recipient?: string | undefined
+  /** Curated route selected by the caller. */
+  route: RouteCandidate
+}
+
+/** Dynamic data returned by an explicit provider quote. */
+export type ProviderQuoteResult = {
+  /** Estimated settlement time in seconds. */
+  estimatedSeconds: number | null
+  /** Provider quote expiry timestamp. */
+  expiresAt: string
+  /** Current and maximum fee summaries. */
+  fees: {
+    /** Current estimated total fee. */
+    total: ProviderQuoteFee
+    /** Maximum total fee allowed by the quote. */
+    totalMax: ProviderQuoteFee
+  }
+  /** Slippage-adjusted minimum destination amount in base units. */
+  minimumOutputAmount: string
+  /** Expected destination amount in base units. */
+  outputAmount: string
+  /** Timestamp when Tempo sampled the quote. */
+  sampledAt: string
+}
+
+/** A normalized explicit funding quote returned to callers. */
+export type FundingQuote = ReturnType<typeof formatFundingQuote>
+
 /** Adapter used to enrich a static route candidate with live provider information. */
 export type ProviderAdapter = {
   /** Probes provider-backed quote information for one static candidate. */
@@ -420,6 +480,12 @@ export type ProviderAdapter = {
 /** Provider adapter registry, keyed by provider id. Missing adapters leave routes static. */
 export type ProviderAdapters = Partial<Record<ProviderId, ProviderAdapter>>
 
+/** Gets a depositor-specific quote without exposing provider execution payloads. */
+export type ProviderQuote = (
+  input: ProviderQuoteInput,
+  signal: AbortSignal,
+) => Promise<ProviderQuoteResult>
+
 /** Static provider support rows used until live quote adapters are configured. */
 const inventory: readonly InventoryEntry[] = [
   { destinationToken: 'usdce', provider: 'across', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
@@ -437,6 +503,7 @@ type InventoryEntry = {
 }
 
 const defaultAdapterTimeoutMs = 750
+const defaultQuoteTimeoutMs = 5_000
 const includes = ['quotes'] as const
 
 /** Lists normalized chains and source tokens that can fund Tempo. */
@@ -455,7 +522,10 @@ export function listProviders(options: listProviders.Options = {}) {
     )
     .map((provider) => ({
       ...formatProvider(provider),
-      status: options.adapters?.[provider.id] ? ('configured' as const) : provider.status,
+      status:
+        options.adapters?.[provider.id] || options.configuredProviders?.includes(provider.id)
+          ? ('configured' as const)
+          : provider.status,
     }))
 }
 
@@ -464,6 +534,8 @@ export declare namespace listProviders {
   type Options = {
     /** Provider adapters configured for this deployment. */
     adapters?: ProviderAdapters | undefined
+    /** Providers configured through capabilities outside discovery adapters. */
+    configuredProviders?: readonly ProviderId[] | undefined
     /** Provider capability to require. */
     capability?: Capability | undefined
   }
@@ -472,7 +544,10 @@ export declare namespace listProviders {
 /** Parses the comma-separated `include` query parameter. */
 export function parseInclude(input: string | undefined) {
   if (input === undefined || input.trim() === '') return []
-  const parsed = input.split(',').map((part) => part.trim()).filter(Boolean)
+  const parsed = input
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
   for (const include of parsed)
     if (!(includes as readonly string[]).includes(include)) throw new UnsupportedIncludeError()
   return [...new Set(parsed)] as readonly Include[]
@@ -506,6 +581,55 @@ export async function listRoutes(options: listRoutes.Options) {
   )
 }
 
+/** Gets a depositor-specific quote for one curated funding route. */
+export async function quoteRoute(options: quoteRoute.Options): Promise<FundingQuote> {
+  const [route] = listStaticRoutes({
+    destinationToken: options.destinationToken,
+    limit: 1,
+    provider: options.provider,
+    sourceAmount: options.sourceAmount,
+    sourceAmountUnits: options.sourceAmountUnits,
+    sourceChain: options.sourceChain,
+    sourceToken: options.sourceToken,
+  })
+  if (!route) throw new FundingRouteNotFoundError()
+
+  const quote = options.quote
+  if (!quote) throw new ProviderNotConfiguredError()
+
+  return formatFundingQuote(
+    route,
+    await runWithTimeout(
+      (signal) =>
+        quote(
+          {
+            depositor: options.depositor,
+            ...(options.recipient === undefined ? {} : { recipient: options.recipient }),
+            route,
+          },
+          signal,
+        ),
+      options.quoteTimeoutMs ?? defaultQuoteTimeoutMs,
+    ),
+  )
+}
+
+export declare namespace quoteRoute {
+  /** Options for resolving and quoting one curated funding route. */
+  type Options = Omit<listStaticRoutes.Options, 'limit' | 'provider'> & {
+    /** Address that would submit the funding transaction. */
+    depositor: string
+    /** Configured provider quote capability. */
+    quote?: ProviderQuote | undefined
+    /** Provider selected for the quote. */
+    provider: 'across'
+    /** Maximum time allowed for the live provider request. */
+    quoteTimeoutMs?: number | undefined
+    /** Optional destination recipient; defaults to the depositor. */
+    recipient?: string | undefined
+  }
+}
+
 /** Lists static funding route candidates for a normalized caller request. */
 export function listStaticRoutes(options: listStaticRoutes.Options) {
   const sourceChain = resolveSourceChain(options.sourceChain)
@@ -608,19 +732,22 @@ async function enrichRoute(
   if (!adapter) return route
 
   try {
-    const quote = await quoteWithTimeout(
-      adapter,
-      {
-        cache: options.cache,
-        destinationChain: route.destinationChain,
-        destinationToken: route.destinationToken,
-        include: options.include,
-        request: options.request,
-        route,
-        sourceAmount: route.sourceAmount,
-        sourceChain: route.sourceChain,
-        sourceToken: route.sourceToken,
-      },
+    const quote = await runWithTimeout(
+      (signal) =>
+        adapter.probeQuote(
+          {
+            cache: options.cache,
+            destinationChain: route.destinationChain,
+            destinationToken: route.destinationToken,
+            include: options.include,
+            request: options.request,
+            route,
+            sourceAmount: route.sourceAmount,
+            sourceChain: route.sourceChain,
+            sourceToken: route.sourceToken,
+          },
+          signal,
+        ),
       options.timeoutMs,
     )
     return {
@@ -754,6 +881,28 @@ function formatRouteQuote(route: RouteCandidate, quote: QuoteProbeResult) {
   } as const
 }
 
+function formatFundingQuote(route: RouteCandidate, quote: ProviderQuoteResult) {
+  return {
+    destinationChain: route.destinationChain,
+    destinationToken: route.destinationToken,
+    estimatedSeconds: quote.estimatedSeconds,
+    expiresAt: quote.expiresAt,
+    fees: quote.fees,
+    inputAmount: route.sourceAmount.amount,
+    minimumOutputAmount: quote.minimumOutputAmount,
+    outputAmount: quote.outputAmount,
+    outputAmountFormatted: decimalFromBaseUnits(
+      quote.outputAmount,
+      route.destinationToken.decimals,
+    ),
+    provider: route.provider,
+    routeId: route.id,
+    sampledAt: quote.sampledAt,
+    sourceChain: route.sourceChain,
+    sourceToken: route.sourceToken,
+  } as const
+}
+
 function markRouteError(route: RouteCandidate, errorCode: string) {
   return {
     ...route,
@@ -770,11 +919,11 @@ function markRouteError(route: RouteCandidate, errorCode: string) {
   }
 }
 
-function quoteWithTimeout(adapter: ProviderAdapter, input: QuoteProbeInput, timeoutMs: number) {
+function runWithTimeout<result>(fn: (signal: AbortSignal) => Promise<result>, timeoutMs: number) {
   const controller = new AbortController()
   const timeout = setTimeout(() => controller.abort(), timeoutMs)
   return Promise.race([
-    adapter.probeQuote(input, controller.signal),
+    fn(controller.signal),
     new Promise<never>((_, reject) => {
       if (controller.signal.aborted) {
         reject(new ProviderAdapterTimeoutError())
@@ -877,11 +1026,31 @@ export class InvalidAmountError extends Error {
   override name = 'FundingRoutes.InvalidAmountError'
 }
 
+/** Error thrown when no curated route matches an explicit quote request. */
+export class FundingRouteNotFoundError extends Error {
+  override name = 'FundingRoutes.FundingRouteNotFoundError'
+}
+
 /** Error thrown internally when a provider adapter exceeds its route quote timeout. */
 export class ProviderAdapterTimeoutError extends Error {
   override name = 'FundingRoutes.ProviderAdapterTimeoutError'
 }
 
+/** Error thrown when a requested provider quote is temporarily unavailable. */
+export class ProviderQuoteUnavailableError extends Error {
+  override name = 'FundingRoutes.ProviderQuoteUnavailableError'
+}
+
+/** Error thrown when a provider rate-limits a quote request. */
+export class ProviderRateLimitError extends Error {
+  override name = 'FundingRoutes.ProviderRateLimitError'
+}
+
+/** Error thrown when a route provider lacks explicit quote capability. */
+export class ProviderNotConfiguredError extends Error {
+  override name = 'FundingRoutes.ProviderNotConfiguredError'
+}
+
 /** Error thrown when the caller filters to an unknown provider. */
 export class UnsupportedProviderError extends Error {
   override name = 'FundingRoutes.UnsupportedProviderError'

package/src/internal/Log.test.ts

@@ -65,8 +65,7 @@ describe('middleware', () => {
     })
     api.get('/secure', (c) => c.json({ ok: true }, 200))
 
-    const token = `tempo:sk:${'a'.repeat(48)}`
-    await api.request(`/secure?apiKey=${token}`)
+    await api.request('/secure?key=opaque-secret&chainId=mainnet')
 
     expect(stable(entries[0]!)).toMatchInlineSnapshot(`
       {
@@ -80,7 +79,7 @@ describe('middleware', () => {
           "orgId": "org_1",
           "type": "api_key",
         },
-        "query": "apiKey=tempo:sk:…",
+        "query": "chainId=mainnet",
         "route": "/secure",
         "status": 200,
       }
@@ -139,6 +138,45 @@ describe('middleware', () => {
     `)
   })
 
+  test('includes redacted provider failure details', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.get('/provider', (c) => {
+      c.set('providerFailure', {
+        code: 'UNAUTHORIZED',
+        failure: 'http',
+        id: 'across',
+        operation: 'swap/approval',
+        status: 401,
+      })
+      return Response.error(c, {
+        code: 'provider_error',
+        message: 'Provider request failed',
+        status: 502,
+      })
+    })
+
+    await api.request('/provider')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "errorCode": "provider_error",
+        "level": "error",
+        "method": "GET",
+        "path": "/provider",
+        "provider": {
+          "code": "UNAUTHORIZED",
+          "failure": "http",
+          "id": "across",
+          "operation": "swap/approval",
+          "status": 401,
+        },
+        "route": "/provider",
+        "status": 502,
+      }
+    `)
+  })
+
   test('logs thrown errors at error level', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })

package/src/internal/Log.ts

@@ -10,6 +10,8 @@ import type * as Timing from './Timing.js'
 export type Variables = {
   /** Stable error code recorded by `Response.error` for the request log entry. */
   errorCode?: string | undefined
+  /** Redacted provider failure details recorded by an upstream adapter. */
+  providerFailure?: Entry['provider'] | undefined
 }
 
 /** Hono environment shape used by the request logger. */
@@ -55,12 +57,27 @@ export type Entry = {
         id: string
         /** Owning organization id for API-key callers. */
         orgId?: string | undefined
-        /** Owning project id for project-attributed API-key callers. */
+        /** Attributed project id for API-key callers. */
         projectId?: string | undefined
         /** Principal kind. */
         type: 'api_key' | 'public' | 'session' | 'super_admin'
       }
     | undefined
+  /** Redacted upstream provider failure details, when an adapter request fails. */
+  provider?:
+    | {
+        /** Stable provider error code, when one is safe to retain. */
+        code?: string | undefined
+        /** Failure boundary that rejected the provider request. */
+        failure: 'http' | 'network' | 'payload' | 'unknown'
+        /** Provider identifier. */
+        id: string
+        /** Provider operation identifier. */
+        operation: string
+        /** Upstream HTTP status, when a response was received. */
+        status?: number | undefined
+      }
+    | undefined
   /** Raw query string (no leading `?`) with API-key tokens redacted, when present. */
   query?: string | undefined
   /** Rate limit state from the `RateLimit-*` response headers, when enforced. */
@@ -110,12 +127,15 @@ export function middleware<environment extends Environment = Environment>(
     const duration = performance.now() - start
 
     const url = new URL(c.req.url)
+    url.searchParams.delete('key')
+    const query = ApiKey.redact(url.search.slice(1))
     const status = c.res.status
     // Hono cannot resolve variable types through the generic `environment`,
     // so shared-variable reads are cast from the environment contract above
     // (the same pattern EdgeCache uses for its cross-layer reads).
     const principal = c.get('principal' as never) as Auth.Principal | undefined
     const errorCode = c.get('errorCode' as never) as string | undefined
+    const provider = c.get('providerFailure' as never) as Entry['provider']
 
     // The `request` total metric duplicates `duration` (measured here, one
     // layer further out), so only operation timings are kept.
@@ -165,9 +185,8 @@ export function middleware<environment extends Environment = Environment>(
               type: principal.type,
             },
           }),
-      // Keys belong in headers, but a confused client may pass one in the
-      // query string; redact defensively before it reaches a log store.
-      ...(url.search.length > 1 ? { query: ApiKey.redact(url.search.slice(1)) } : {}),
+      ...(provider === undefined ? {} : { provider }),
+      ...(query ? { query } : {}),
       ...(rateLimit === undefined ? {} : { rateLimit }),
       requestId: c.get('requestId' as never) as string,
       route: c.req.routePath,